setsuzoku 0.10.1

data/lib/setsuzoku/service.rb

@@ -0,0 +1,70 @@
+# typed: false
+# frozen_string_literal: true
+
+module Setsuzoku
+  # Core service required for a web service plugin.
+  # It should be able to register all of its available api and auth strategies.
+  # It acts as the orchestration between a plugin, auth_strategy, and api_strategy.
+  module Service
+    autoload :WebService, 'setsuzoku/service/web_service'
+
+    extend Forwardable
+    extend T::Sig
+    extend T::Helpers
+    abstract!
+
+    attr_accessor :plugin
+    attr_accessor :auth_strategy
+    attr_accessor :api_strategy
+    attr_accessor :external_api_handler
+    def_delegators :@auth_strategy, :new_credential!
+    def_delegators :@api_strategy, :call_external_api, :request_class
+
+    def self.included(klass)
+      klass.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      extend T::Sig
+      extend T::Helpers
+      abstract!
+
+      # The api and auth strategies available for the service.
+      # api: { simple_name: ApiModule }
+      #
+      # @return [Hash(Hash(Class))] the available_strategies object for the Service.
+      sig { abstract.returns(T::Hash[Symbol, T::Hash[Symbol, Class]]) }
+      def available_strategies; end
+    end
+
+    # Initialize the plugin_service by setting its auth and api strategies.
+    #
+    # @param auth_strategy [AuthStrategy] the auth_strategy for the service to use.
+    # @param api_strategy [ApiStrategy] the api_strategy for the service to use.
+    #
+    # @return [Service] the new instance of service with its correct strategies.
+    sig(:final) do
+      params(
+          plugin: T.untyped,
+          strategies: T::Hash[Symbol, T.untyped],
+          args: T.untyped
+      ).returns(T.any(Setsuzoku::Service::WebService::Service, T.untyped))
+    end
+    def initialize(plugin:, strategies:, **args)
+      #TODO: here we need to assign credentials etc, I think.
+      self.plugin = plugin
+      self.external_api_handler = Setsuzoku.external_api_handler.new
+
+      # iterate over all strategies this plugin's service uses and set their configuration
+      strategies.each do |strategy, attrs|
+        # get the strategy type from auth_strategy/api_strategy etc.
+        type = T.must(strategy.to_s.split("_strategy").first).to_sym
+        strat = attrs[:strategy]
+        # associate the strategy with the service
+        self.send("#{strategy}=", self.class.available_strategies[type][strat].new(service: self, credential: args[:credential], **attrs.except(:strategy)))
+      end
+
+      self
+    end
+  end
+end

data/lib/setsuzoku/service/web_service.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+require 'setsuzoku/service/web_service/api_strategy'
+require 'setsuzoku/service/web_service/auth_strategy'
+require 'setsuzoku/service/web_service/service'
+require 'setsuzoku/service/web_service/api_strategies/rest_strategy'
+require 'setsuzoku/service/web_service/api_strategies/rest_api_request'
+require 'setsuzoku/service/web_service/auth_strategies/o_auth_strategy'
+require 'setsuzoku/service/web_service/auth_strategies/basic_auth_strategy'
+require 'setsuzoku/service/web_service/credentials/o_auth_credential'
+require 'setsuzoku/service/web_service/credentials/basic_auth_credential'
+
+module Setsuzoku
+  module Service
+    module WebService
+      # Core service required for a web service plugin.
+      # It should be able to register all of its available api and auth strategies.
+    end
+  end
+end

data/lib/setsuzoku/service/web_service/api_strategies/rest_api_request.rb

@@ -0,0 +1,17 @@
+
+# typed: false
+# frozen_string_literal: true
+
+module Setsuzoku
+  module Service
+    module WebService
+      module ApiStrategies
+        class RestAPIRequest < T::Struct
+          prop :action, Symbol, default: nil
+          prop :body, T::Hash[T.untyped, T.untyped], default: {}
+          prop :without_headers, T::Boolean, default: false
+        end
+      end
+    end
+  end
+end

data/lib/setsuzoku/service/web_service/api_strategies/rest_strategy.rb

@@ -0,0 +1,155 @@
+# typed: false
+# frozen_string_literal: true
+
+require 'active_support/json'
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/string/access'
+
+module Setsuzoku
+  module Service
+    module WebService
+      module ApiStrategies
+        # Defines all necessary methods for handling interfacing with a REST API.
+        class RestStrategy < WebService::ApiStrategy
+          extend T::Sig
+          extend T::Helpers
+
+          def request_class
+            RestAPIRequest
+          end
+
+          def self.required_instance_methods
+            []
+          end
+
+          # Make a REST API request.
+          # 1. Format the request and send it via the appropriate HTTP method.
+          # 2. Format the response and return it.
+          #
+          # @param request [RestAPIRequest] the constructed API request object.
+          # @param action_details [Hash] the action details for the action to execute.
+          # @param options [Any] additional options needed to pass to correctly perform the request.
+          # options are:
+          #   media_type - 'json'
+          #
+          # @return [Hash] the parsed response object.
+          sig { override.params(request: T.untyped, action_details: T::Hash[T.untyped, T.untyped], options: T.untyped).returns(Faraday::Response) }
+          def perform_external_call(request:, action_details:, **options)
+            request_properties = self.get_request_properties(action_name: request.action, action_details: action_details, req_params: request.body)
+            request_options = self.request_options(request_properties[:request_format], action_details[:actions][request.action])
+
+            full_request = self.formulate_request(request_properties, request_options)
+
+            @faraday = Faraday.new(url: request_properties[:formatted_full_url]) do |faraday|
+              faraday.request(:multipart) if options[:attachments].present?
+              faraday.request(:url_encoded)
+              # faraday.basic_auth(request_options[:basic_auth][:username], request_options[:basic_auth][:password]) if request_options[:basic_auth]
+              faraday.request(:basic_auth, request_options[:basic_auth][:username], request_options[:basic_auth][:password]) if request_options[:basic_auth]
+              # faraday.response request_properties[:response_format] if request_properties[:response_format]
+              faraday.authorization(:Bearer, request_properties[:token]) if request_properties[:token]
+              # request_options[:headers][:Authorization].prepend('Bearer ') if request_options[:headers][:Authorization]
+              faraday.adapter Faraday.default_adapter
+            end
+
+            if options[:attachments].present?
+              resp = @faraday.post do |req|
+                io = StringIO.new(full_request)
+                payload = {}
+                payload[:json] = Faraday::UploadIO.new(io, 'application/json')
+                payload[:attachment] = options[:attachments].map{ |file| Faraday::UploadIO.new(file[0], file[1], file[2]) }
+                req.body = payload
+              end
+            else
+              @faraday.headers = request_options[:headers] if request_options[:headers]
+              resp = @faraday.send(request_properties[:request_method], request_properties[:formatted_full_url], full_request)
+            end
+            resp
+          end
+
+          sig do
+            params(
+                action_name: Symbol,
+                for_stub: T::Boolean,
+                req_params: T::Hash[T.untyped, T.untyped],
+                action_details: T::Hash[Symbol, T.untyped]
+            ).returns(T::Hash[Symbol, T.untyped])
+          end
+
+          def get_request_properties(action_name:, for_stub: false, req_params: {}, action_details: { actions: self.plugin.api_actions, url: self.plugin.api_base_url })
+            action = action_details[:actions][action_name]
+            request_method, endpoint = action.first
+            request_method = request_method.downcase.to_sym
+            request_format = action[:request_type]
+            response_format = action[:response_type]
+            token = action[:token]
+            stub_data = action[:stub_data] if for_stub
+            full_url = action_details[:url] + endpoint
+            formatted_full_url, req_params = self.replace_dynamic_vars(full_url: full_url, req_params: req_params)
+            {
+                request_method: request_method,
+                endpoint: endpoint,
+                request_format: request_format,
+                response_format: response_format,
+                formatted_full_url: formatted_full_url,
+                req_params: req_params,
+                stub_data: stub_data,
+                token: token
+            }
+          end
+
+          # Create the proper request body based on the request_properties and request_options passed
+          #
+          # @param request_properties [Hash] information pertaining to the body of the request
+          # @param request_options [Hash] information pertainint to the headers of the request
+          #
+          # @return full_request [Hash/String] returns the request body in the format required
+          def formulate_request(request_properties = {}, request_options = {})
+            request_format = request_properties.dig(:request_format).to_s
+            content_type = request_options.dig(:headers, :'Content-Type').to_s
+
+            if request_properties[:request_method] == :get || request_properties[:req_params].empty?
+              request_properties[:req_params]
+            else
+              # if the header or request format and request format include urlencoded return the body as a hash
+              if request_format.include?('urlencoded') && content_type.include?('urlencoded')
+                request_properties[:req_params]
+              else
+                # return either xml or json
+                if request_properties[:request_format] == :xml
+                  convert_hash_to_xml(request_properties[:req_params])
+                else
+                  request_properties[:req_params].to_json
+                end
+              end
+            end
+        end
+
+          def request_options(request_format = nil, action_details = {})
+            request_options = self.auth_strategy.auth_headers.merge(self.plugin.api_headers).merge(action_details[:request_options] || {})
+            (request_options[:headers] ||= {})[:'Content-Type'] = "application/#{request_format || :json}"
+            request_options
+          end
+
+          def replace_dynamic_vars(full_url:, req_params: {})
+            # replace matching vars in the action with matching params.
+            # scans the string for variables like {{number_sid}} and replaces it with the matching key in params
+            # removes the params variable, as it's probably intended to be in the url only. If you encounter a need to have
+            # it in the body and the url, then you should put it in params twice with different names.
+            req_params = req_params.dup
+            full_url = full_url.dup
+            dynamic_vars = self.plugin.dynamic_url_params.merge(req_params).with_indifferent_access
+            full_url.scan(/({{.*?}})/).flatten.each do |var|
+              var_name = var.tr('{{ }}', '')
+              next unless dynamic_vars[var_name]
+
+              full_url.gsub!(var, dynamic_vars[var_name])
+              req_params.delete(var_name)
+              req_params.delete(var_name.to_sym)
+            end
+            [full_url, req_params]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/setsuzoku/service/web_service/api_strategy.rb

@@ -0,0 +1,169 @@
+# typed: true
+# frozen_string_literal: true
+
+module Setsuzoku
+  module Service
+    # Defines all common methods for handling interfacing with a Web Service API.
+    module WebService
+
+      class ApiStrategy
+        include Setsuzoku::ApiStrategy
+        extend T::Sig
+        extend T::Helpers
+
+        # These are interface methods that a plugin that implements this strategy must implement.
+        module InterfaceMethods
+          extend T::Sig
+          extend T::Helpers
+          interface!
+
+          # The base Web Service API URL for the plugin.
+          #
+          # @return [String] the API base url.
+          sig { abstract.returns(String) }
+          def api_base_url; end
+
+          # the base webhook api url
+          #
+          # @return [String] the webhook base url
+          def webhook_base_url; end
+
+          # The collection of all implemented endpoints for the API.
+          # Formatted as: { api_action: { 'HTTP_VERB': 'api.com/endpoints' } }
+          #
+          # @return [Hash] all endpoint definitions for the API.
+          sig { abstract.returns(T::Hash[T.untyped, T.untyped]) }
+          def api_actions; end
+
+          # Any api request headers that this service needs to set.
+          #
+          # @return [Hash]
+          sig { abstract.returns(T::Hash[Symbol, T.untyped]) }
+          def api_headers; end
+
+          # All dynamic url parameters provided by the plugin.
+          #
+          # @return [Hash(String)] all parameters that need to be replaced dynamically for url requests.
+          sig { abstract.returns(T::Hash[Symbol, T.nilable(String)]) }
+          def dynamic_url_params; end
+        end
+
+        # Perform the external call for the external API.
+        # Each WebService::ApiStrategy must define how this works.
+        #
+        # It should:
+        # 1. Make the external request
+        # 2. Parse the response
+        # 3. Handle any bad response
+        # 4. Format the response
+        #
+        # @param request [APIRequest] the request object to be used for the request. Each strategy defines its request structure.
+        # @param action_details [Hash] the action_details for the action to execute.
+        # @param options [Any] any additional options needed to pass to correctly perform the request.
+        #
+        # @return [Any] the formatted response object.
+        sig { override.params(request: T.untyped, action_details: T::Hash[T.untyped, T.untyped], options: T.untyped).returns(T.untyped) }
+        def perform_external_call(request:, action_details:, **options); end
+
+        # Parse the response from the API for the given request.
+        # This should just convert JSON strings/XML/SQL rows to a formatted response Hash.
+        #
+        # @param response [HTTParty::Response] the response from the HTTP request.
+        # @param options [Hash] the parsing options. Generally the response_type. e.g. :xml, :json
+        #
+        # @return [Hash] the parsed hash of the response object.
+        sig { override.params(response: Faraday::Response, options: T.untyped).returns(T::Hash[Symbol, T.untyped]) }
+        def parse_response(response:, **options)
+          case options[:response_type]
+          when :json
+            JSON.parse(response.body).deep_symbolize_keys
+          when :xml
+            convert_xml_to_hash(response.body)
+          else
+            JSON.parse(response.body).deep_symbolize_keys
+          end
+        end
+
+        private
+
+        sig { params(hash: T::Hash[Symbol, T.untyped], mutate_keys: T::Boolean).returns(String)}
+        def convert_hash_to_xml(hash, mutate_keys = true)
+          hash = hash.map do |k, v|
+                  text = if v.is_a?(Hash)
+                           convert_hash_to_xml(v)
+                         elsif v.is_a?(Array)
+                           v.map do |elem|
+                             convert_hash_to_xml(elem)
+                           end.join
+                         else
+                            v
+                         end
+                  k = k.to_s.camelize if mutate_keys
+                  "<%s>%s</%s>" % [k, text, k]
+          end.join
+          hash
+        end
+
+        # Convert an XML string to a usable hash.
+        sig { params(xml: String).returns(T::Hash[Symbol, T.untyped])}
+        def convert_xml_to_hash(xml)
+          begin
+            result = Nokogiri::XML(xml)
+            return { result.root.name.underscore.to_sym => xml_node_to_hash(result.root)}
+          rescue Exception => e
+            {}
+          end
+        end
+
+        def xml_node_to_hash(node)
+          # If we are at the root of the document, start the hash
+          if node.element?
+            result_hash = {}
+            if node.attributes != {}
+              attributes = {}
+              node.attributes.keys.each do |key|
+                attributes[node.attributes[key].name.underscore.to_sym] = node.attributes[key].value
+              end
+            end
+            if node.children.size > 0
+              node.children.each do |child|
+                result = xml_node_to_hash(child)
+
+                if child.name == "text"
+                  unless child.next_sibling || child.previous_sibling
+                    return result unless attributes
+                    result_hash[child.name.underscore.to_sym] = result
+                  end
+                elsif result_hash[child.name.to_sym]
+
+                  if result_hash[child.name.to_sym].is_a?(Array)
+                    result_hash[child.name.underscore.to_sym] << result
+                  else
+                    result_hash[child.name.underscore.to_sym] = [result_hash[child.name.to_sym]] << result
+                  end
+                else
+                  stripped_children = node.children.reject{ |n| n.text.strip.blank? }
+                  if stripped_children.length > 1 && stripped_children.combination(2).all? { |a,b| a.name == b.name }
+                    return result_hash[node.name.underscore.to_sym] = stripped_children.map{|n| xml_node_to_hash(n) }
+                  else
+                    result_hash[child.name.underscore.to_sym] = result
+                  end
+                end
+              end
+              if attributes
+                #add code to remove non-data attributes e.g. xml schema, namespace here
+                #if there is a collision then node content supersets attributes
+                result_hash = attributes.merge(result_hash)
+              end
+              return result_hash
+            else
+              return attributes
+            end
+          else
+            return node.content.to_s
+          end
+        end
+      end
+    end
+  end
+end

data/lib/setsuzoku/service/web_service/auth_strategies/basic_auth_strategy.rb

@@ -0,0 +1,50 @@
+# typed: ignore
+# frozen_string_literal: true
+
+module Setsuzoku
+  module Service
+    module WebService
+      module AuthStrategies
+        # The API OAuth Authentication Interface definition.
+        # Any Plugin that implements this must implement all methods required for OAuth.
+        #
+        # Defines all necessary methods for handling authentication for any authentication strategy.
+        class BasicAuthStrategy < WebService::AuthStrategy
+          extend T::Sig
+          extend T::Helpers
+
+          def self.required_instance_methods
+            []
+          end
+
+          def self.credential_class
+            Setsuzoku::Service::WebService::Credentials::BasicAuthCredential
+          end
+
+          # OAuth API authentication headers.
+          #
+          # @return [Hash(String)] the formatted authorization headers for an OAuth request
+          sig { override.returns(T::Hash[Symbol, T.untyped]) }
+          def auth_headers
+            {
+                basic_auth: {
+                    username: self.credential.username,
+                    password: self.credential.password
+                }
+            }
+          end
+
+
+          # if the auth credientials are valid
+          #
+          #
+          # sig { override.returns(T::Boolean) }
+          def auth_credential_valid?
+            true
+          end
+
+        end
+      end
+    end
+  end
+end