razorrisk-razor-connectivity 0.14.10

data/lib/razor_risk/razor/connectivity/razor_3/razor_requester.rb

@@ -0,0 +1,559 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+#
+#  Class for connecting to the Razor application via the RazorRequest
+#  executable.
+#
+#  Copyright (c) 2017 Razor Risk Technologies Pty Limited. All rights reserved.
+#
+# ######################################################################## #
+
+
+# ######################################################################## #
+# requires
+
+require 'razor_risk/razor/connectivity/razor_3/response'
+require 'razor_risk/razor/connectivity/exceptions'
+
+require 'razor_risk/core/system/system_traits'
+
+require 'razor_risk/core/diagnostics/logger'
+
+require 'nokogiri'
+require 'pantheios'
+require 'recls'
+require 'xqsr3/quality/parameter_checking'
+require 'xqsr3/extensions/string/quote_if'
+
+require 'open3'
+require 'tempfile'
+
+# ######################################################################## #
+# modules
+
+module RazorRisk
+module Razor
+module Connectivity
+module Razor3
+
+# ######################################################################## #
+# classes
+
+# Class that provides easy call interface to Razor, following along with the
+# "traditional" behaviour of the RazorRequest tool
+#
+# It is used by creating an instance, which requires the ClarITe config
+# (path) and the Razor Environment name, as in:
+#
+#   +rr = RazorRequester.new cc_path, env_name
+#
+# and then requests are dispatched to the relevant Razor installation (as
+# named by the environment) via the +send_request+ method, as in:
+#
+#   +rr.send_request request
+#
+# where +request+ is a Razor request document.
+#
+# Both initialiser and +send_request+ methods take options, as detailed in
+# their respective documentation sections. The initialiser's +:executable+
+# option is required when the class method +requires_executable?+ returns
+# +true+, and should point to the full path of the underlying RazorRequest
+# program to be used for connectivity with the Razor system
+class RazorRequester
+
+    include ::Pantheios
+    include ::Xqsr3::Quality::ParameterChecking
+    include ::RazorRisk::Core::Diagnostics::Logger
+    private
+    def nil_if_empty v
+
+        return nil if v.respond_to?(:empty?) && v.empty?
+        v
+    end
+    def to_nil *args; end
+    def self.to_nil *args; end
+    public
+
+    # FIXME: THIS MUST BE FIXED.
+    #
+    # Validate that all characters in the string are alphanumerics, spaces,
+    # or underscores.
+    #
+    # This check is temporary and does not grantee SQL safety. This
+    # must be addressed as a larger issue around sanitization of user
+    # inputs to Razor.
+    #
+    # @param str [String] The string to be validated.
+    #
+    # @yield Executes the block if the string is not safe.
+    #
+    # @raise [ArgumentError] If the argument is not a string.
+    # @raise [ArgumentError] If the argument is not a string.
+    #
+    # @example Raise an exception if unsafe.
+    #   stopgap_sql_string_validator_fix_me '.!?' { raise ArgumentError }
+    def self.stopgap_sql_string_validator_fix_me str, &block
+
+        raise ArgumentError.new 'No block was given' unless block_given?
+
+        check_parameter str, 'str', type: ::String
+
+        unless /^[A-Za-z0-9_ ]+$/ =~ str
+            yield
+        end
+    end
+
+    # see #stopgap_sql_string_validator_fix_me
+    def stopgap_sql_string_validator_fix_me *args, &block
+        self.class.stopgap_sql_string_validator_fix_me(*args, &block)
+    end
+
+    # ##########################################################
+    # types
+
+    # Root exception for failures of RazorRequester
+    class Exception < ::RazorRisk::Razor::Connectivity::Exceptions::ConnectivityException
+    end
+
+    # Exception thrown when request fails
+    class RequestFailedException < Exception
+
+        def initialize message, exit_status, razor_code, contingent_report, **options
+
+            trace ParamNames[ :message, :exit_status, :razor_code, :contingent_report, :options ], message, exit_status, razor_code, contingent_report, options
+
+            if (message || '').empty?
+
+                message =   contingent_report
+            else
+
+                if (contingent_report || '').empty?
+
+                    ;
+                else
+
+                    message = "#{message}: #{contingent_report}"
+                end
+            end
+
+            super message, options
+
+            @exit_status        =   exit_status
+            @razor_code         =   razor_code
+            @contingent_report  =   contingent_report
+        end
+
+        attr_reader :exit_status
+        attr_reader :razor_code
+        attr_reader :contingent_report
+
+        def inspect
+
+            "#<#{self.class}:0x00#{object_id << 1}: exit_status=#{exit_status}; razor_code=#{razor_code}; contingent_report=#{contingent_report}>"
+        end
+    end
+
+    # Raised when the response from the +:razor_executable+ is not
+    # recognised (which might mean an invalid executable has been specified)
+    class InvalidResponseException < Exception; end
+
+    # Raised when the credentials given are invalid
+    class InvalidCredentialsException < RequestFailedException; end
+
+    # Represents the executable
+    class Executable
+
+        include RazorRisk::Core::System::SystemTraits
+
+        include ::Xqsr3::Quality::ParameterChecking
+        include ::Xqsr3::Quality::ParameterChecking
+
+        module Constants
+
+            RRParameters = {
+                username:           '/usr',
+                password:           '/pwd',
+                domain:             '/domain',
+                impersonatee:       '/impersonate',
+                razor_space:        '/space',
+                razor_environment:  '/env',
+                razor_alias:        '/alias',
+                session_id:         '/sessionId',
+            }
+
+            RROptions = {
+                debug:          '/debug',
+                logStderr:      '/logStderr',
+                session:        '/session',
+                open_session:   '/openSession',
+            }
+        end
+
+        # Initialises the instance
+        #
+        # @param executable [::String, Array<::String>] As string with 1 or
+        #   more elements separated by '|' (or by the platform's separator -
+        #   ';' on Windows; ':' otherwise)
+        #
+        def initialize executable
+
+            check_parameter executable, 'executable', types: [ ::String, [ ::String ] ]
+
+            exec_parts  =   executable.split(windows? ? /[|;]/ : /[|:]/) if ::String === executable
+            exec_parts  =   exec_parts.flatten
+            exec_parts  =   exec_parts.reject { |xp| xp.strip.empty? }
+
+            raise ::ArgumentError, "the given executable '#{executable}' resolves to nothing" if exec_parts.empty?
+
+            arg0        =   exec_parts.shift
+
+            @arg0       =   Recls.stat(arg0) or raise ArgumentError, "given executable '#{arg0}' does not exist"
+            @argv       =   exec_parts
+        end
+
+        # Forms the full command to be executed, based on the given
+        # parameters, options, and also on the nature of the executable
+        # specified in the initialiser
+        #
+        # @param config_path [::String] The ClarITe configuration
+        # @param request_path [::String] The path of the request document.
+        # @param options [::Hash] Options hash
+        #
+        # @option options [::String] :username The user to use fro the
+        #   credentials.
+        # @option options [::String] :password The password to use for
+        #   credentials.
+        # @option options [::String] :domain The domain to use for
+        #   credentials.
+        # @option options [::String] :impersonatee The user to impersonate.
+        # @option options [::String] :razor_environment The Razor environment.
+        # @option options [Boolean] :session Uses a Razor session for the
+        #   request.
+        # @option options [Boolean] :debug Turns on debug.
+        # @option options [Boolean] :log_to_stderr Turns on logging.
+        #
+        # @return [::String] The command to execute.
+        def form_command config_path, request_path, **options
+
+            cmd = []
+            cmd << program_path.to_s.quote_if
+
+            unless program_arguments.empty?
+
+                program_arguments.each do |arg|
+
+                    cmd << arg.quote_if
+                end
+            else
+
+                cmd << '/config' << config_path.quote_if
+                cmd << '/request' << request_path.quote_if unless request_path.nil?
+
+                Constants::RRParameters.each do |key,value|
+                    cmd << value << options[key].quote_if if options[key]
+                end
+
+                Constants::RROptions.each do |key,value|
+                    cmd << value if options[key]
+                end
+            end
+
+            cmd * ' '
+        end
+
+        def program_path; @arg0; end
+        def program_arguments; @argv; end
+    end
+
+    # Indicates whether the instance requires an executable
+    def self.requires_executable?
+
+        true
+    end
+
+    # Initialises an instance with configuration and set-up options
+    #
+    # @param config [::String, nil] The ClarITe configuration. By default
+    #   this is interpreted as a file path, unless the option
+    #   +:config_as_string+ is given. If +nil+ it will be obtained from
+    #   option +:config+. One or the other must be supplied.
+    # @param options [::Hash] The options hash.
+    #
+    # @option options [::String] :config The ClarITe configuration. By
+    #   default this is interpreted as a file path, unless the option
+    #   +:config_as_string+ is given. Ignored if the parameter +config+ is
+    #   not +nil+.
+    # @option options [::String] :razor_environment Specifies the Razor
+    #   environment. May not be combinbed with +:razor_alias+.
+    # @option options [::String] :razor_space Specifies the ClarITe
+    #   space. May not be combinbed with +:razor_alias+.
+    # @option options [::String] :razor_alias Specifies the Razor alias. May
+    #   not be combinbed with +:razor_environment+ or +:razor_space+.
+    # @option options [Boolean] :config_as_string The +config+ parameter
+    #   [or +:config+ option] is treated as a string containing the
+    #   configuration, rather than the path to a configuration file.
+    # @option options [::String] :executable Specifies the executable for
+    #   RazorRequest. Required if the class method +requires_executable?+ is
+    #   +true+. May contain program arguments, separated using the
+    #   platform-independent path separator '|' [or the platform-specific
+    #   path separator - ';' for Windows; ':' otherwise].
+    # @option options :aborter DEPRECATED
+    #
+    def initialize config, **options
+
+        trace ParamNames[ :config, :options ], config, options
+
+        check_parameter config, 'config', type: ::String, allow_nil: true
+
+        warn ':aborter option is not longer recognised' if options[:aborter]
+
+        # NOTE: This (ctor) method concerns itself only with specifying (and
+        # validating) the executable and the configuration
+
+        config          =   nil_if_empty(config) || nil_if_empty(options[:config]) or raise ArgumentError, 'config not specified'
+
+        unless options[:config_as_string]
+            raise ArgumentError, "given config file '#{config}' does not exist, or is not a file" unless File.file? config
+        end
+
+        unless options[:razor_environment] or options[:razor_alias]
+            raise ArgumentError, 'either :razor_environment or :razor_alias options must be specified'
+        end
+
+        if self.class.requires_executable?
+
+            executable  =   options[:executable]  or raise ArgumentError, ':executable option is required'
+
+            @executable =   Executable.new executable
+        end
+
+        @config         =   config
+        @options        =   options
+    end
+
+    attr_reader :config
+    attr_reader :options
+
+    def executable
+        @executable.program_path
+    end
+
+    def environment
+        @options[:razor_environment] || @options[:razor_alias]
+    end
+
+    # Sends the given request.
+    #
+    # @param request [#to_s] The string form of this object is used as the
+    #   request.
+    # @param options [::Hash] The options hash.
+    #
+    # @option options [::String] :username The username part of the
+    #   credentials.
+    # @option options [::String] :password The password to be specified as
+    #   part of the credentials. Ignored unless +options[:username]+ is
+    #   specified.
+    # @option options [::String] :domain The domain to be specified as part
+    #   of the credentials. Ignored unless options +:username]+ is specified.
+    # @option options [::String] :impersonatee The name of the account that
+    #   will be impersonated for the purposes of the request.
+    # @option options [Boolean] :session Causes a Razor session to be used
+    #  for the request.
+    # @option options [Boolean] :request_as_path The +request+ parameter is
+    #   treated as a path to a file containing the request contents, rather
+    #   than the request contents.
+    # @option options [Boolean] :debug Causes certain debugging actions,
+    #   including not removing temporary files.
+    # @option options [Boolean] :log_to_stderr Causes the RazorRequest CLI
+    #   flag '/logStderr' to be included in the command-line.
+    # @option options :request_as_string DEPRECATED
+    #
+    def send_request request, **options
+
+        trace ParamNames[ :request, :options ], request, options
+
+        options.reject! { |k,v| v.empty? if v.respond_to? :empty? }
+
+        unless (options[:username] && options[:password]) ||
+                options[:single_sign_on]                  ||
+                options[:impersonatee]                    ||
+                options[:session_id]
+            raise ArgumentError, 'Some form of credentials must be provided.'
+        end
+
+        # Disable session option if session already provided
+        options[:session] = false if options[:session_id]
+
+        options = @options.merge options.reject { |k| [ :config_as_string, :config ].include? k }
+
+        raise ArgumentError, ':request_as_string option no longer supported' if options[:request_as_string]
+
+        if (options[:razor_environment] or options[:razor_space]) and options[:razor_alias]
+            raise ArgumentError, 'option :razor_alias may not be combined with :razor_environment or :razor_space'
+        end
+
+        warn ':domain option will be ignored as no username was specified' if options[:domain] and not options[:username]
+        warn ':password option will be ignored as no username was specified' if options[:password] and not options[:username]
+
+        if options[:config_as_string]
+
+            tf = Tempfile.new('clarite_config')
+
+            begin
+
+                cc_path = tf.path
+
+                tf.close
+
+                File.open(cc_path, 'w') do |f|
+
+                    f.write @config
+                    f.write "\n"
+                end
+
+                do_send_request_ cc_path, request, options.reject { |k| k == :config_as_string }
+            ensure
+
+                File.unlink(cc_path)
+            end
+        else
+
+            do_send_request_ @config, request, options
+        end
+    end
+
+    private
+    def do_send_request_ config_path, request, options
+
+        trace ParamNames[ :config_path, :request, :options ], config_path, request, options
+
+        unless options[:request_as_path] || request.nil?
+
+            rq_file = Tempfile.new('request_document')
+
+            begin
+
+                rq_file.write request
+                rq_file.write "\n"
+                rq_file.flush
+                rq_file.rewind
+
+                return do_send_request_ config_path, rq_file.path, options.merge({ :request_as_path => true })
+            ensure
+
+                rq_file.close
+                rq_file.unlink unless options[:debug]
+            end
+        end
+
+        options[:log_to_stderr] = options[:log_to_stderr] || options[:debug]
+
+        cmd = @executable.form_command config_path, request, **options
+
+        log :debug0, 'cmd: \'', cmd, '\''
+
+        t_before    =   Time.now
+
+        stdout_str, stderr_str, status = Open3.capture3 cmd
+
+        t_after     =   Time.now
+
+        if severity_logged? :debug1
+
+            log :debug1, 'stderr: \'', stderr_str.chomp, '\''
+            log :debug1, 'stdout: \'', stdout_str.chomp, '\''
+            log :debug1, 'status: \'', status, '\''
+        end
+
+        log :benchmark, "execution of RazorRequest(.exe) (in #{self.class}##{__method__}): dt=#{(t_after - t_before) * 1000}ms" if severity_logged?(:benchmark)
+
+        exit_status = status.exitstatus
+        
+        if 0 != exit_status
+
+            # Current version of RazorRequest writes its contingent report to
+            # stdout - I know! - when it fails (with non-0 exit code), so we
+            # must parse that
+
+            cr_str              =   options[:log_to_stderr] ? stderr_str : stdout_str
+
+            cr_lines            =   cr_str.split(/[\r\n]/)
+            contingent_report   =   cr_lines[-1]
+
+            # now parse the CR to extract the Razor code
+
+            rzc = nil
+
+            cr_lines.each_with_index do |line0, index0|
+
+                line    =   line0.chomp
+                index   =   1 + index0
+
+                unless rzc
+
+                    rzc = $1 if line =~ /^(RZC\d+)\s+(.*)$/
+                end
+            end
+
+            log :debug2, "contingent report lines:\n\t#{cr_lines.join(%Q<\n\t>)}" if options[:debug] && severity_logged?(:debug2)
+
+            x_class = RequestFailedException
+
+            if 15 == exit_status || cr_lines.any? { |line| line =~ /RAZOR log[io]n failed/i }
+
+                x_class = InvalidCredentialsException
+            end
+
+            raise x_class.new "request failed", exit_status, rzc, contingent_report, contingent_report_lines: cr_lines
+        else
+
+            # record stderr
+
+            contingent_report   =   stderr_str.split(/[\r\n]/)
+
+            log :debug2, "contingent report lines:\n\t#{contingent_report.join(%Q<\n\t>)}" if options[:debug] && severity_logged?(:debug2)
+        end
+        
+        if stdout_str.split(/[\r\n]/) == ["<ack>queued</ack>"]
+            response     = ::Nokogiri.XML(stdout_str)
+        else
+            xml_doc     =   begin
+
+                ::Nokogiri.XML(stdout_str) { |config| config.strict }
+            rescue ::Nokogiri::XML::SyntaxError => x
+
+                raise InvalidResponseException.new 'invalid response', cause: x
+            end
+
+            log(:debug4) { "xml_doc: #{xml_doc.to_xml}" }
+
+            begin
+
+                response    =   Response.new xml_doc
+            rescue ArgumentError => x
+
+                raise InvalidResponseException.new 'invalid response', cause: x
+            end
+
+            log :debug3, 'response: ', response
+        end
+
+        log :debug3, 'response: ', response
+        response
+    end
+    public
+
+end
+
+# ######################################################################## #
+# modules
+
+end # module Razor3
+end # module Connectivity
+end # module Razor
+end # module RazorRisk
+
+# ############################## end of file ############################# #
+
+