razorrisk-cassini-common 0.26.24

data/lib/razor_risk/cassini/util/program_execution_util.rb

@@ -0,0 +1,379 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+#
+#  Utility methods for creating commands to execute microservices.
+#
+#  Copyright (c) 2018 Razor Risk Technologies Pty Limited. All rights reserved.
+#
+# ######################################################################## #
+
+
+require 'razor_risk/core/system/system_traits'
+
+require 'pantheios'
+require 'recls'
+require 'xqsr3/quality/parameter_checking'
+
+require 'uri'
+
+require 'razor_risk/core/diagnostics/logger'
+
+module RazorRisk
+module Cassini
+module Util
+
+module ProgramExecutionUtil
+
+    include ::RazorRisk::Core::System::SystemTraits
+
+    include ::Pantheios
+    include ::Xqsr3::Quality::ParameterChecking
+
+    include ::RazorRisk::Core::Diagnostics::Logger
+
+    module Util_Internals_
+
+        include ::Pantheios
+
+    end # module Util_Internals_
+
+    module Constants
+        module SecretServer
+            DEFAULT_NAME = 'secret-server'
+        end
+    end
+
+    class Command < ::Array
+
+        def cmd
+            self[0]
+        end
+
+        def uri
+            self[1]
+        end
+    end
+
+    private
+    def add_command_element_ s, a0, a1 = nil, **options
+
+        trace
+
+        case a0
+        when ::String
+
+            ;
+
+        when ::Recls::Entry
+
+            a0  =   a0.to_str
+        else
+        end
+
+        case a1
+        when ::String
+
+            ;
+        when nil
+
+            ;
+        when ::Recls::Entry
+
+            a1  =   a1.to_str
+        else
+        end
+
+        a0  =   %Q<"#{a0}"> if a0.include? ' '
+        a1  =   %Q<"#{a1}"> if a1 && a1.to_s.include?(' ')
+
+        if options[:use_equal]
+
+            "#{s} #{a0}=#{a1}"
+        else
+
+            r   =   "#{s} #{a0}"
+            r   +=  " #{a1}" if a1
+
+            r
+        end
+    end
+    public
+
+    def program_name_from_executable p
+
+        p.to_s.split(windows? ? /[;|]/ : /[:|]/)[0]
+    end
+
+    def make_secretserver_command \
+        cassini_root_directory,
+        secrets_path,
+        host,
+        port,
+        **options
+
+        trace ParamNames[ :cassini_root_directory, :secrets_path, :host, :port, :options ], cassini_root_directory, secrets_path, host, port, options
+
+        check_parameter cassini_root_directory, 'cassini_root_directory', types: [ ::Recls::Entry, ::String ]
+        check_parameter port, 'port', type: ::Integer
+
+        # 1. Form command
+
+        cmd = if options[:ruby_path]
+            options[:ruby_path]
+        else
+            "ruby" + (Recls::Ximpl::OS::OS_IS_WINDOWS ? '.exe' : '')
+        end
+
+        cmd     =   add_command_element_ cmd, '-d' if options[:debug]
+
+        if options[:path]
+
+            cmd =   add_command_element_ cmd, options[:path]
+        else
+
+            cmd =   add_command_element_ cmd, Recls.combine_paths(cassini_root_directory, 'tools/utilities', Constants::SecretServer::DEFAULT_NAME, 'ws.rb', canonicalise: true)
+        end
+
+        cmd     =   add_command_element_ cmd, '-h', host if host
+
+        cmd     =   add_command_element_ cmd, '-p', port
+
+        cmd     =   add_command_element_ cmd, '-w', options[:web_server] if options[:web_server]
+
+        cmd     =   add_command_element_ cmd, Recls.combine_paths(cassini_root_directory, secrets_path, canonicalise: true)
+
+        if lt = options[:log_threshold]
+
+            case lt
+            when :debug4, 'debug4'
+
+                lt  =   :debug
+            when ::Array
+
+                lt  =   lt.empty? ? nil : lt.join(',')
+            else
+
+            end
+
+            cmd =   add_command_element_ cmd, '--log-threshold', lt, use_equal: true
+        end
+
+        if ld = options[:log_directory]
+            cmd =   add_command_element_ cmd, '--log-directory', ld, use_equal: true
+        end
+
+        pr_name =   options[:program_name] || Constants::SecretServer::DEFAULT_NAME
+
+        cmd     =   add_command_element_ cmd, '--program-name', pr_name, use_equal: true
+
+        if rc = options[:routes_config]
+
+            cmd =   add_command_element_ cmd, rc
+        end
+
+
+        # 2. Form URL
+
+        url_path=   '/'
+        scheme  =   options[:uri_scheme] || 'http'
+        host    ||= 'localhost'
+        path    =   '/' == (url_path || '')[0] ? url_path : '/' + url_path
+        url     =   "#{scheme}://#{host}:#{port}#{path}"
+        uri     =   URI.parse url
+
+
+        # 3. Form return value
+
+        log :debug2, 'creating secret server: url=\'', url, '\'; cmd=\'', cmd, ?'
+
+        Command.[](cmd, uri)
+    end
+
+    # Creates a string that can be used to start a mircoservice from the CLI.
+    #
+    # @param microservice_name [::String] The name of the microservice.
+    # @param security_model [:basic, :authorisation_only, :jwt] The security
+    #   model the microservice is to use.
+    # @param razor_executable [::String] The path to the RazorRequest
+    #   executable file.
+    # @param cassini_root_directory [::String] The path to the root direcotry
+    #   Cassini is installed in.
+    # @param clarite_config_path [::String] The path the ClarITe config XML
+    #   file.
+    # @param host [::String] The URI host the microservice will be
+    #   accessible at.
+    # @param port [::String] The URI port the microservice will be accessible
+    #   at.
+    # @param url_path [::String] The URL path the microservice will be
+    #   accessible at.
+    # @param options [::Hash] The options hash.
+    #
+    #
+    # @option options [::String] razor_environment The Razor environment to
+    #   connect to.
+    # @option options [::String] razor_space The Razor space to
+    #   connect to.
+    # @option options [::String] razor_alias The Razor alias to
+    #   connect to.
+    # @option options [Boolean] :benchmark Causes the child processes to be
+    #   run with benchmarking enabled.
+    # @option options [Boolean] :debug Determines whether to run child
+    #   processes in debug mode.
+    # @option options [::Symbol] :log_threshold Specifies the log-threshold
+    #   to be used with the child process.
+    # @option options ['http', 'https'] :uri_scheme Determines whether to the
+    #   target URI is to be hit with the HTTPS protocol, rather than HTTP.
+    # @option options [::String] :path Specifies a specific path to be used,
+    #   thereby suppressing the normal inference mechanism.
+    # @option options [::String, Array<::String>] :additional_arguments Some
+    #   additional arguments to be incorporated, which will be ...
+    #
+    # @return [Array<::String, ::String>] A tuple of command + URL
+    def make_microservice_command \
+        microservice_name,
+        security_model,
+        razor_executable,
+        cassini_root_directory,
+        clarite_config_path,
+        host,
+        port,
+        url_path,
+        **options
+
+        trace ParamNames[ :microservice_name, :security_model, :razor_executable, :cassini_root_directory, :clarite_config_path, :host, :port, :url_path, :options ], microservice_name, security_model, razor_executable, cassini_root_directory, clarite_config_path, host, port, url_path, options
+
+        check_parameter security_model, 'security_model', type: ::Symbol, values: [ :basic, :authorisation_only, :jwt ]
+        check_parameter cassini_root_directory, 'cassini_root_directory', types: [ ::Recls::Entry, ::String ]
+        check_parameter port, 'port', type: ::Integer
+
+
+        # 1. Form command
+
+        cmd = if options[:ruby_path]
+            options[:ruby_path]
+        else
+            "ruby" + (Recls::Ximpl::OS::OS_IS_WINDOWS ? '.exe' : '')
+        end
+
+        cmd     =   add_command_element_ cmd, '-d' if options[:debug]
+
+        rel_l1  =   options[:restful] ? 'tools/services/restful' : 'tools/services'
+
+        if options[:path]
+
+            cmd =   add_command_element_ cmd, options[:path]
+        else
+
+            cmd =   add_command_element_ cmd, Recls.combine_paths(cassini_root_directory, rel_l1, microservice_name, 'ws.rb', canonicalise: true)
+        end
+
+        cmd     =   add_command_element_ cmd, '-x', [razor_executable].flatten.join(windows? ? ';' : ':') if razor_executable
+        cmd     =   add_command_element_ cmd, '-e', options[:razor_environment] if options[:razor_environment]
+        cmd     =   add_command_element_ cmd, '--razor-alias', options[:razor_alias] if options[:razor_alias]
+        cmd     =   add_command_element_ cmd, '--razor-space', options[:razor_space] if options[:razor_space]
+
+        case security_model
+        when :basic
+
+            sm  =   'b'
+        when :authorisation_only
+
+            sm  =   'a'
+        when :jwt
+
+            sm  =   'j'
+        else
+
+            log :violation, 'unrecognised security model \'', security_model, ?'
+        end
+
+        cmd = add_command_element_ cmd, '-a', sm
+        cmd = add_command_element_ cmd, '-h', host if host
+        cmd = add_command_element_ cmd, '-p', port
+        cmd = add_command_element_ cmd, '-o', clarite_config_path if clarite_config_path
+        cmd = add_command_element_ cmd, '-s', options[:secret_server] if options[:secret_server]
+        cmd = add_command_element_ cmd, '-j', options[:jwt_encoding_algorithm] if options[:jwt_encoding_algorithm]
+        cmd = add_command_element_ cmd, '-w', options[:web_server] if options[:web_server]
+        cmd = add_command_element_ cmd, '-u', options[:web_ui_server] if options[:web_ui_server]
+        cmd = add_command_element_ cmd, '--benchmark' if options[:benchmark]
+        cmd = add_command_element_ cmd, '--authorization-test-mode' if options[:auth_test_mode]
+
+        if lt = options[:log_threshold]
+
+            case lt
+            when :debug4, 'debug4'
+
+                lt  =   :debug
+            when ::Array
+
+                lt  =   lt.empty? ? nil : lt.join(',')
+            else
+
+            end
+
+            cmd =   add_command_element_ cmd, '--log-threshold', lt, use_equal: true
+        end
+
+        if ld = options[:log_directory]
+            cmd =   add_command_element_ cmd, '--log-directory', ld, use_equal: true
+        end
+
+        pr_name =   options[:program_name] || microservice_name
+
+        cmd     =   add_command_element_ cmd, '--program-name', pr_name, use_equal: true
+
+        if rc = options[:routes_config]
+
+            cmd =   add_command_element_ cmd, rc
+        end
+
+        case aa = options[:additional_arguments]
+        when nil
+
+            ;
+        when ::Array
+
+            aa.each do |a|
+
+                case a
+                when ::Array
+
+                    warn "processing additional arguments array element that does not contain exactly two elements" unless 2 == a.size
+
+                    cmd =   add_command_element_ cmd, a[0], a[1], use_equal: true
+                else # ::String
+
+                    cmd =   add_command_element_ cmd, a
+                end
+            end
+
+        else # ::String
+
+            cmd =   add_command_element_ cmd, aa
+        end
+
+        # 2. Form URL
+
+        scheme  =   options[:uri_scheme] || 'http'
+        host    ||= 'localhost'
+        path    =   '/' == (url_path || '')[0] ? url_path : "/#{url_path}"
+        url     =   "#{scheme}://#{host}:#{port}#{path}"
+        uri     =   URI.parse url
+
+        # 3. Form return value
+
+        log :debug2, 'creating microservice: url=\'', url, '\'; cmd=\'', cmd, ?'
+
+        Command.[](cmd, uri)
+    end
+
+end # module ProgramExecutionUtil
+
+end # module Util
+end # module Cassini
+end # module RazorRisk
+
+# ############################## end of file ############################# #
+
+

data/lib/razor_risk/cassini/util/secrets_util.rb

@@ -0,0 +1,229 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/cassini/util/secrets_util.rb
+#
+# Purpose:      Security functions
+#
+# Created:      25th November 2017
+# Updated:      15th February 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2017-2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+# ##########################################################################
+# requires
+
+require 'razor_risk/extensions/hash/dig'
+require 'razor_risk/core/diagnostics/logger'
+
+require 'pantheios'
+require 'recls'
+require 'xqsr3/extensions/hash/deep_transform'
+require 'xqsr3/quality/parameter_checking'
+
+require 'json'
+require 'net/http'
+require 'resolv-replace'
+require 'yaml'
+
+module RazorRisk
+module Cassini
+module Util
+
+# Include-module that introduces the +load_secrets+ function
+module SecretsUtil
+
+    include ::Pantheios
+    include ::Xqsr3::Quality::ParameterChecking
+    include ::RazorRisk::Core::Diagnostics::Logger
+
+    def included receiver
+
+        receiver.extend self
+    end
+
+    # Gets the given secret - +category+ + +algorithm+ - from the given
+    # server (+secret_server_url+), according to the given options
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +secret_server_url+:: [ ::String, ::URI ] The URI of the secret
+    #     server
+    #   - +category+:: [ ::String, ::Symbol ] The secret category. May be
+    #     +nil+
+    #   - +algorithm+:: [ ::String, ::Symbol ] The secret algorithm
+    #
+    # NOTE: all algorithm names are converted to lowercase before processing
+    def get_secret_from_server secret_server_url, category, algorithm, **options
+
+        trace ParamNames[ :secret_server_url, :category, :algorithm, :options ], secret_server_url, category, algorithm, options
+
+        check_parameter secret_server_url, 'secret_server_url', types: [ ::String, ::URI::Generic ]
+        check_parameter algorithm, 'algorithm', types: [ ::String, ::Symbol ]
+        check_parameter category, 'category', types: [ ::String, ::Symbol ], allow_nil: true
+
+        uri     =   URI.parse secret_server_url
+        host    =   uri.host
+        port    =   uri.port
+
+        headers =   {
+
+            'Accept' => 'application/json',
+        }
+
+        params  =   { 'algorithm' => algorithm }
+
+        params['category'] = category if category
+
+        headers.reject! { |k, v| ::NilClass === v }
+
+        begin
+
+            # there are issues in sending through a path-less URI to the
+            # server, so we step in and assign it (as the root) if it
+            # does not exist
+
+            path    =   (uri.path || '').empty? ? '/' : uri.path
+            query   =   URI.encode_www_form params
+
+            log :debug0, "host: '#{host}'; port: '#{port}'; path: '#{path}'; query: '#{query}'"
+
+            response = Net::HTTP.start(host, port, :use_ssl => uri.scheme == 'https') do |http|
+
+                full_uri    =   URI::HTTP.build host: host, port: port, path: path, query: query
+                full_url    =   full_uri.to_s
+
+                log :debug0, 'issuing request to \'', full_uri, '\'; scheme=\'', uri.scheme, '\''
+
+                request = Net::HTTP::Get.new full_uri, headers
+
+                http.request request
+            end
+
+            if '200' != response.code.to_s
+
+                abort "could not obtain secret for algorithm '#{algorithm}' from server '#{secret_server_url}': #{response.code}: #{response.body}"
+            end
+
+            j = JSON.parse response.body
+
+            j['secret']
+        rescue Errno::ECONNREFUSED
+
+            log :warning, 'failed to contact secret server ', secret_server_url
+
+            return nil
+        end
+    end
+
+    def get_secret_from_hash h, category, algorithm, **options
+
+        trace ParamNames[ :h, :category, :algorithm, :options ], h, category, algorithm, options
+
+        check_parameter h, 'h', type: ::Hash
+        check_parameter algorithm, 'algorithm', types: [ ::String, ::Symbol ]
+        check_parameter category, 'category', types: [ ::String, ::Symbol ], allow_nil: true
+
+        h           =   h['secrets'] if 1 == h.size && h.has_key?('secrets')
+
+        h           =   h.deep_transform { |k, v| [ k.to_s.downcase, v ] }
+
+        category    ||= 'all'
+
+        category    =   category.downcase
+        algorithm   =   algorithm.downcase
+
+        secret      =   nil
+        secret      ||= h.dig(category, algorithm) if 'all' != category
+        secret      ||= h.dig('all', algorithm)
+
+        secret
+    end
+
+    # Loads the secrets for the given algorithms from the given source
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +source+:: [::String, ::URI] The source of the secrets, which may
+    #     be a URI of a secret server, or the path of a YAML file
+    #   - +algorithms+:: An array of algorithms (::String or ::Symbol), or
+    #     [ category, algorithm ] tuples
+    #   - +options+:: Options
+    #
+    # * *Options:*
+    #   - +:source_is+:: [::Symbol] If +:uri+, then +source+ is assumed to be
+    #     a  specified, then +source+ type is inferred from its type and
+    #     content
+    #
+    # === Returns
+    #   A hash representing the obtained secrets
+    #
+    # NOTE: all algorithm names are converted to lowercase before processing
+    def load_secrets source, *algorithms, **options
+
+        trace ParamNames[ :source, :algorithms, :options ], source, algorithms, options
+
+        check_parameter source, 'source', types: [ ::String, ::URI::Generic ]
+        check_parameter algorithms, 'algorithms', types: [ [ ::String, ::Symbol ] ]
+        check_option options, :source_is, type: ::Symbol, values: [ :path, :uri ], allow_nil: true
+
+        source_is   =   options[:source_is]
+
+        source_is   ||= :uri if ::URI::Generic === source
+        source_is   ||= :path if Recls.stat(source) rescue nil
+        source_is   ||= :uri if URI.parse(source) rescue nil
+
+        raise ArgumentError, "could not identify whether source - '#{source}' - is a file-system path or a URI" unless source_is
+
+        acs     =   algorithms.map do |a|
+
+            alg =   nil
+            cat =   nil
+
+            case a
+            when ::String, ::Symbol
+
+                alg =   a.to_s.downcase
+            else
+
+                log :warning, "unexpected element - '#{a}' (#{a.class}) - in array argument"
+            end
+
+            [ cat, alg ]
+        end.reject { |ar| ar[1].nil? }
+
+        secrets =   {}
+
+        yaml    =   YAML.load_file(source) if :path == source_is
+
+        acs.each do |category, algorithm|
+
+            if :uri == source_is
+
+                secrets[algorithm] = get_secret_from_server source, category, algorithm, **options
+            else
+
+                secrets[algorithm] = get_secret_from_hash yaml, category, algorithm, **options
+            end
+        end
+
+        secrets
+    end
+
+end # module SecretsUtil
+
+end # module Util
+end # module Cassini
+end # module RazorRisk
+
+# ############################## end of file ############################# #
+
+

data/lib/razor_risk/cassini/util/version_util.rb

@@ -0,0 +1,88 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/cassini/util/version_util.rb
+#
+# Purpose:      Conducts claimed version checks
+#
+# Created:      2nd January 2018
+# Updated:      15th May 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+# ##########################################################################
+# requires
+
+require 'pantheios'
+require 'xqsr3/quality/parameter_checking'
+
+=begin
+=end
+
+module RazorRisk
+module Cassini
+module Util
+
+module VersionUtil
+
+    include ::Pantheios
+    include ::Xqsr3::Quality::ParameterChecking
+
+    def self.included receiver
+
+        receiver.extend self
+    end
+
+    # Checks the required and actual version of a given library, aborting
+    # with a detailed message if not compatible
+    #
+    # === Signature
+    #
+    # * *Parameters:*
+    #   - +actual_module_or_version+:: [ ::Module, ::String, [ ::String,
+    #     Integer]] The module or version being tested. Recommended usage is
+    #     to pass the module (which allows inference of the name)
+    #   - +required_version+:: [ ::String, [ ::Integer ]] The required
+    #     version, e.g. [ 0, 1, 2, 3] or '0.1.2.3'
+    #   - +lib_name+:: [::String] The name of the library. May be +nil+ if
+    #     +actual_module_or_version+ is a +::Module+, the name of which will
+    #     be used instead
+    #
+    # * *Options:*
+    #   - +:aborter+:: [ responds to :abort(::String) ] An aborter. May be
+    #     +nil+, in which case +::Kernel+ is used
+    #   - +:process_name+:: [::String] The name of the process. May be
+    #     +nil+, in which case it is inferred from the calling script
+    def check_version_compatibility actual_module_or_version, required_version, lib_name = nil, **options
+
+        check_parameter actual_module_or_version, 'actual_module_or_version', types: [ ::Module, [ ::String, ::Integer ], ::String ]
+        check_parameter required_version, 'required_version', types: [ [ ::String, ::Integer ], ::String ]
+
+        check_option options, :aborter, allow_nil: true, responds_to: [ :abort ]
+
+        aborter         =   options[:aborter] || ::Kernel
+        process_name    =   options[:process_name] || ::Pantheios::Util::ProcessUtil.derive_process_name
+
+        lib_name        ||= actual_module_or_version.to_s if ::Module === actual_module_or_version
+
+        actual_version  =   ::Module === actual_module_or_version ? actual_module_or_version::VERSION : actual_module_or_version
+        required_s      =   ::Array === required_version ? required_version.join('.') : required_version
+
+        aborter.abort "#{process_name}: FATAL: this program requires #{lib_name} version #{required_s} or later" if ::Pantheios::Util::VersionUtil.version_compare(required_version, actual_version) > 0
+    end
+
+end # module VersionUtil
+
+end # module Util
+end # module Cassini
+end # module RazorRisk
+
+# ############################## end of file ############################# #
+
+