razorrisk-cassini-common 0.26.24

data/lib/razor_risk/cassini/extensions/libclimate/common_options.rb

@@ -0,0 +1,267 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/cassini/extensions/libclimate/common_options.rb
+#
+# Purpose:      Extensions to libCLImate's LibCLImate::Climate class that
+#               are relevant to Cassini
+#
+# Created:      19th December 2017
+# Updated:      7th November 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2017-2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+require 'libclimate'
+
+require 'highline/import'
+require 'recls'
+require 'xqsr3/extensions/string/map_option_string'
+require 'xqsr3/quality/parameter_checking'
+
+require 'resolv'
+require 'socket'
+
+require 'razor_risk/core/diagnostics/logger'
+
+=begin
+=end
+
+module LibCLImate
+
+class Climate
+    include ::RazorRisk::Core::Diagnostics::Logger
+    def option_web_server program_options, **options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--web-server', alias: '-w', help: 'specifies the web-server', required: options[:required]) do |o, a|
+
+            program_options[:web_server] = o.value or self.abort "invalid web server '#{o.value}'; use --help for usage"
+        end
+    end
+
+    def option_username program_options, **options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--username', help: 'specifies the username', required: options[:required]) do |o, a|
+
+            program_options[:username] = o.value or self.abort "invalid username '#{o.value}'; use --help for usage"
+        end
+    end
+
+    def option_password program_options, **options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--password', help: 'specifies the password. If no password is supplied, the user will be prompted for it', required: options[:required]) do |o, a|
+
+            password = o.value
+
+            if (password || '').empty?
+
+                password = $terminal.ask('enter password: ') { |q| q.echo = '*' }
+            end
+
+            program_options[:password] = password
+        end
+    end
+
+    def option_domain program_options, **options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--domain', help: 'specifies the domain', required: options[:required]) do |o, a|
+
+            program_options[:domain] = o.value or self.abort "invalid domain '#{o.value}'; use --help for usage"
+        end
+    end
+
+
+    def option_host program_options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--host', alias: '-h', help: 'specifies the host. Defaults to \'localhost\' in development; \'0.0.0.0\' otherwise. May also specify one of the host\'s adaptors, via a sentinel of the form \'adaptor-0\', \'adaptor-1\', ... or \'adaptor-?\' to get a list of available adaptors') do |o, a|
+
+            v = o.value or self.abort "invalid host '#{o.value}'; use --help for usage"
+
+            if /^adapt[eo]r-\?$/ =~ v
+
+                self.abort "available adaptors:\n#{Socket.ip_address_list.select { |ai| ai.ipv4_private? }.map.with_index(0) { |ai, index| "\t#{index}:\t#{ai.ip_address}" }.join(%<\n>)}", exit: 0
+            end
+
+            if /^adapt[eo]r-([0-9-]+)$/ =~ v
+
+                index       =   Integer $1
+
+                address     =   Socket.ip_address_list.select { |ai| ai.ipv4_private? }[index]
+
+                self.abort "invalid adaptor index #{index}" if index < 0
+                self.abort "this machine does not have a private adaptor at index #{index}. Specify 'adaptor-?' to obtain list of available adaptor addresses; use --help for usage" unless address
+
+                v           =   address.ip_address
+            else
+
+                begin
+
+                    v = 'localhost' == v.downcase ? '127.0.0.1' : Resolv.getaddress(v)
+                rescue => x
+
+                    self.abort "exception (#{x.class}) thrown when attempting to resolve given host name '#{v}': #{x}"
+                end
+            end
+
+            program_options[:host] = v
+        end
+    end
+
+    def option_port program_options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--port', alias: '-p', help: 'specifies the port. Required', required: true, required_message: "\0Port") do |o, a|
+
+            program_options[:port] = Integer(o.value, nil: true) or self.abort "invalid port '#{o.value}'; use --help for usage"
+        end
+    end
+
+    def option_clarite_config_path program_options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--clarite-config-path', alias: '-o', help: 'specifies the path of the ClarITe config file. Required', required: true, required_message: "\0ClarITe configuration path") do |o, a|
+
+            program_options[:clarite_config_path] = o.value or self.abort "invalid ClarITe config path '#{o.value}'; use --help for usage"
+        end
+    end
+
+    def option_authentication_scheme program_options, schemes, **options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+        ::Xqsr3::Quality::ParameterChecking.check_parameter schemes, 'schemes', type: [ ::String ]
+
+        self.add_option('--authentication-scheme', alias: '-a', help: "specifies the authentication scheme. Must be one of #{schemes.map { |s| %Q{'#{s}'} }.join(', ')}. Defaults to 'jwt'. If 'jwt', this requires a value to be provided for <jwt-secret-server-url>, which will be used to look up all the algorithms by the '--jwt-encoding-algorithm' and '--credentials-encoding-algorithm' as well as those specified as additional values", required: options[:required]) do |o, a|
+
+            program_options[:authentication_scheme] = (o.value || '').map_option_string(schemes) or self.abort "invalid authorisation scheme '#{o.value}'; use --help for usage"
+        end
+
+        self.add_flag('--authorization-test-mode', help: "specifies that the web services should be in authorization test mode which does not perform authentication. THIS MUST NOT BE USED IN PRODUCTION.") do |o, a|
+
+            program_options[:auth_test_mode] = true
+        end
+    end
+
+    # TODO: DEPRECIATED.
+    def option_credentials_encoding_algorithm program_options, **options
+
+        self.add_option('--credentials-encoding-algorithm', alias: '-c', help: 'Credentials encoding algorithm has been depreciated.') do |o, a|
+
+            log :warning, 'Credentials encoding algorithm has been depreciated.'
+        end
+    end
+
+    def option_jwt_encoding_algorithm program_options, **options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--jwt-encoding-algorithm', alias: '-j', help: 'specifies the JWT encoding algorithm (for which a secret must be retrieved). Required if the authentication scheme is \'jwt\'', required: options[:required]) do |o, a|
+
+            program_options[:jwt_encoding_algorithm] = o.value or self.abort "invalid JWT encoding algorithm '#{o.value}'; use --help for usage"
+        end
+    end
+
+    def option_secret_server_source program_options, **options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--secret-server-source', alias: '-s', help: 'specifies the secret server source, which may be the URL of a secret-server, or the path of a secrets file. Required if authentication scheme is \'jwt\'') do |o, a|
+
+            program_options[:secret_server_source] = o.value or self.abort "invalid secret server source '#{o.value}'; use --help for usage"
+        end
+    end
+
+    def option_razor_environment program_options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--razor-environment', alias: '-e', help: 'specifies the Razor environment name.') do |o, a|
+
+            program_options[:razor_environment] = o.value or self.abort "invalid Razor environment '#{o.value}'; use --help for usage"
+        end
+    end
+
+    def option_razor_alias program_options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--razor-alias', help: 'specifies the Razor alias.') do |o, a|
+
+            program_options[:razor_alias] = o.value or self.abort "invalid Razor alias '#{o.value}'; use --help for usage"
+        end
+    end
+
+    def option_razor_space program_options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--razor-space', help: 'specifies the Razor space.') do |o, a|
+
+            program_options[:razor_space] = o.value or self.abort "invalid Razor space '#{o.value}'; use --help for usage"
+        end
+    end
+
+    def option_razor_executable program_options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--razor-executable', alias: '-x', help: 'specifies the Razor executable path. Required', required: true, required_message: "\0Razor executable") do |o, a|
+
+            program_options[:razor_executable] = o.value or self.abort "invalid Razor executable path '#{o.value}'; use --help for usage"
+        end
+    end
+
+    def option_tls_cert_and_key program_options
+
+        ::Xqsr3::Quality::ParameterChecking.check_parameter program_options, 'program_options', type: ::Hash
+
+        self.add_option('--tls-certificate-file', help: 'specifies the TLS/SSL certificate file. If it has the extension \'.crt\' then the path will be used to infer the TLS/SSL public-key file with the extension \'.key\', otherwise the option \'--tls-public-key-file\' is required') do |o, a|
+
+            fe = Recls.stat(o.value) or self.abort "invalid/non-existant TLS certificate file '#{o.value}'; use --help for usage"
+
+            program_options[:tls_certificate_file] = fe.path
+
+            unless program_options[:tls_public_key_file]
+
+                if fe.extension == '.crt'
+
+                    key_path = fe.path[0...-4] + '.key'
+
+                    if File.exist? key_path
+
+                        program_options[:tls_public_key_file] = key_path
+                    end
+                end
+            end
+        end
+
+        self.add_option('--tls-public-key-file', help: 'specifies the TLS/SSL public-key file') do |o, a|
+
+            fe = Recls.stat(o.value) or self.abort "invalid/non-existant TLS public-key file '#{o.value}'; use --help for usage"
+
+            program_options[:tls_public_key_file] = fe.path
+        end
+    end
+end
+
+end # module LibCLImate
+
+# ############################## end of file ############################# #
+
+

data/lib/razor_risk/cassini/extensions/libclimate.rb

@@ -0,0 +1,26 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/cassini/extensions/libclimate.rb
+#
+# Purpose:      RazorRisk LibCLImate extensions
+#
+# Created:      19th December 2017
+# Updated:      4th March 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2017-2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+# ##########################################################################
+# requires
+
+require 'razor_risk/cassini/extensions/libclimate/common_options'
+
+# ############################## end of file ############################# #
+
+

data/lib/razor_risk/cassini/header_functions.rb

@@ -0,0 +1,59 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/cassini/header_functions.rb
+#
+# Purpose:      ::RazorRisk::Cassini::HeaderFunctions module
+#
+# Created:      25th November 2017
+# Updated:      4th March 2018
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2017-2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+# ##########################################################################
+# requires
+
+require 'razor_risk/cassini/constants'
+
+=begin
+=end
+
+module RazorRisk
+module Cassini
+
+module HeaderFunctions
+
+    #
+    # @return A hash, which will be empty when the scheme is not
+    def make_WWW_auth_header auth_by
+
+        case auth_by
+        when :basic
+
+            { 'WWW-Authenticate' => 'Basic' + ' realm="system", error="missing_token", error_description="The Authorization header was not supplied, or was empty"' }
+        when :authorisation_only
+
+            { 'WWW-Authenticate' => Constants::SCHEME_AUTH_ONLY + ' realm="system", error="missing_token", error_description="The Authorization header was not supplied, or was empty"' }
+        when :jwt
+
+            { 'WWW-Authenticate' => 'Bearer' + ' realm="system", error="missing_token", error_description="The Authorization header was not supplied, or was empty"' }
+        else
+
+            {}
+        end
+    end
+
+end # module HeaderFunctions
+
+end # module Cassini
+end # module RazorRisk
+
+# ############################## end of file ############################# #
+
+

data/lib/razor_risk/cassini/main.rb

@@ -0,0 +1,238 @@
+# encoding: UTF-8
+
+# ######################################################################## #
+# File:         razor_risk/cassini/main.rb
+#
+# Purpose:      Main entry file for a Cassini application
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2018, Razor Risk Technologies Pty Ltd
+# All rights reserved.
+#
+# ######################################################################## #
+
+
+# ##########################################################################
+# requires
+
+require 'razor_risk/cassini/cli'
+require 'razor_risk/cassini/constants'
+require 'razor_risk/cassini/diagnostics/util_functions'
+require 'razor_risk/cassini/extensions/libclimate'
+require 'razor_risk/cassini/util/secrets_util'
+
+require 'razor_risk/razor/connectivity/razor_3/razor_requester'
+
+require 'razor_risk/core/diagnostics/extensions/libclimate'
+
+require 'razor_risk/core/diagnostics/logger'
+
+require 'libclimate'
+
+require 'pantheios'
+
+require 'xqsr3/extensions/kernel/integer'
+
+# ##########################################################################
+# at_exit
+
+at_exit do
+
+    class MainProgramLogic
+
+        extend ::RazorRisk::Cassini::Util::SecretsUtil
+        extend ::RazorRisk::Cassini::Diagnostics
+
+        include ::RazorRisk::Cassini::Constants
+        include ::RazorRisk::Razor::Connectivity::Razor3
+
+        include ::RazorRisk::Core::Diagnostics::Logger
+
+        module Constants
+
+            module Defaults
+
+                LOGGING_THRESHOLD   =   [ :informational, :debug ]
+            end # module Defaults
+        end # module Constants
+
+        def self.run!
+
+            abort "use of razor_risk/cassini/main requires definition of the constant TheApp" unless defined? TheApp
+
+            program_features    =   TheApp::PROGRAM_FEATURES.dup
+
+            program_features[:cli_has_web_server]   =   program_features[:has_web_server]
+
+            program_features[:cli_has_host] =   program_features[:has_host]
+            program_features[:cli_has_port] =   program_features[:has_port]
+
+            if program_features[:has_host_and_port]
+
+                program_features[:cli_has_host] =   true
+                program_features[:cli_has_port] =   true
+            end
+
+            if program_features[:has_razor_connectivity]
+
+                program_features[:cli_has_clarite_config_path] = true
+                program_features[:cli_has_razor_executable]    = RazorRequester.requires_executable?
+                program_features[:cli_has_razor_environment]   = true
+                program_features[:cli_has_razor_space]         = true
+                program_features[:cli_has_razor_alias]         = true
+            end
+
+            if program_features[:authentication]
+
+                program_features[:cli_has_authentication_scheme]  = true
+                program_features[:cli_has_jwt_encoding_algorithm] = true
+                program_features[:cli_has_secret_server_source]   = true
+            end
+
+            program_features[:copyright_year]   ||= 2018
+
+            cli_usage_values    =   program_features[:cli_usage_values]
+
+            # ##########################################################################
+            # command-line parsing
+
+            options =   {}
+
+            climate = LibCLImate::Climate.new do |cl|
+
+                cl.option_web_server options if program_features[:cli_has_web_server]
+
+                cl.option_host options if program_features[:cli_has_host]
+                cl.option_port options if program_features[:cli_has_port]
+
+                cl.option_clarite_config_path options if program_features[:cli_has_clarite_config_path]
+                cl.option_razor_executable options if program_features[:cli_has_razor_executable]
+                cl.option_razor_environment options if program_features[:cli_has_razor_environment]
+                cl.option_razor_space options if program_features[:cli_has_razor_space]
+                cl.option_razor_alias options if program_features[:cli_has_razor_alias]
+
+                cl.option_authentication_scheme options, SUPPORTED_AUTHENTICATION_SCHEMES if program_features[:cli_has_authentication_scheme]
+                cl.option_jwt_encoding_algorithm options if program_features[:cli_has_jwt_encoding_algorithm]
+                cl.option_secret_server_source options if program_features[:cli_has_secret_server_source]
+
+                cl.option_log_threshold options, default_level: Constants::Defaults::LOGGING_THRESHOLD, limit: -2
+
+                cl.info_lines = [
+
+                    ::RazorRisk::Cassini::Common::DESCRIPTION,
+                    ::RazorRisk::Cassini::CLI.Copyright(program_features[:copyright_year]),
+                    :version,
+                    TheApp.full_description,
+                ]
+
+                cl.usage_values = cli_usage_values if cli_usage_values
+            end
+
+            r = climate.run ARGV
+
+            # ##########################################################################
+            # sorting the diagnostic loggin
+
+            ::Pantheios::Core.program_name = options[:program_name] if options[:program_name]
+
+            program_name    =   ::Pantheios::Core.program_name
+            log_directory   =   options[:log_directory] || './logs'
+            log_threshold   =   options[:log_threshold] || Constants::Defaults::LOGGING_THRESHOLD
+
+            setup_diagnostic_logging program_name, log_directory, log_threshold
+
+            # ##########################################################################
+            # amass the arguments that are required
+
+            log :debug2, 'checking all required arguments are provided'
+
+            options[:host] ||= nil
+
+            if program_features[:authentication]
+
+                climate.abort 'authentication scheme not specified; use --help for usage' unless options[:authentication_scheme]
+
+                secret_server_source = options[:secret_server_source] or climate.abort 'no secret server url specified; use --help for usage' if :jwt == options[:authentication_scheme]
+
+                case options[:authentication_scheme]
+                when :jwt
+
+                    options[:jwt_encoding_algorithm] or climate.abort "must specify JWT encoding algorithm; use --help for usage"
+                    algorithms = r.values.empty? ? [ options[:jwt_encoding_algorithm] ] : r.values
+                else
+
+                    algorithms = []
+                end
+            end
+
+            # ##########################################################################
+            # main
+
+            if :jwt == options[:authentication_scheme]
+                log :informational, 'loading secrets ...'
+                options[:secrets] = load_secrets(secret_server_source, *algorithms)
+            else
+                options[:secrets] = {}
+            end
+
+            log :informational, 'initialising Razor connector ...'
+            log :debug0, 'options: ', options
+
+            begin
+
+                rr_options                  = {}
+                rr_options[:executable]     = options[:razor_executable] if RazorRequester.requires_executable?
+                rr_options[:razor_environment]    = options[:razor_environment]
+                rr_options[:razor_space]          = options[:razor_space]
+                rr_options[:razor_alias]          = options[:razor_alias]
+
+                options[:razor_requester] = RazorRequester.new options[:clarite_config_path], **rr_options
+            rescue ::ArgumentError, ::NameError, ::NoMethodError, ::TypeError => x
+
+                log :violation, "unexpected exception (#{x.class}): '#{x.message}': #{x.backtrace}"
+
+                raise
+            rescue => x
+
+                log :alert, "exception(#{x.class}): #{x.message}"
+
+                climate.abort x.message
+            end
+
+            log :informational, 'initialising application ...'
+            log :debug0, 'options: ', options
+
+            begin
+
+                TheApp.init_service **options
+            rescue ::ArgumentError, ::NameError, ::NoMethodError, ::TypeError => x
+
+                log :violation, "unexpected exception (#{x.class}): '#{x.message}': #{x.backtrace}"
+
+                raise
+            rescue ::Errno::EADDRINUSE => x
+
+                log :debug, x.message
+                msg = "Cannot start #{self.process_name}, '#{options[:host]}:#{options[:port]}' in use"
+                log :critical, msg
+                climate.abort msg
+            rescue => x
+
+                log :alert, "exception(#{x.class}): #{x.message}"
+
+                climate.abort x.message
+            end
+
+            log :notice, 'starting ', TheApp::SHORT_DESIGNATION, ' server', options[:authentication_scheme] ? " with authentication scheme '#{options[:authentication_scheme]}'" : ''
+
+            TheApp.run!
+        end
+    end
+
+    MainProgramLogic.run!
+end
+
+# ############################## end of file ############################# #
+
+