opensecret 0.0.2 → 0.0.4

data/lib/opensecret/commons/eco.cmdline.rb

@@ -0,0 +1,446 @@
+#!/usr/bin/ruby
+
+# -- --------------------------------------------------------------------------------- -- #
+# -- The [Command Interpreter]                                                         -- #
+# -- --------------------------------------------------------------------------------- -- #
+# --                                                                                   -- #
+# -- From the command line we receive the below asset groups.                          -- #
+# --                                                                                   -- #
+# --   [1] - major use case commands like "create", "register", "destroy"              -- #
+# --   [2] - specifiers telling us "create what", "destroy which ones"                 -- #
+# --   [3] - boolean flags that dictate which way the hammer should fall               -- #
+# --   [4] - option / arg config pairs (options can be long or short)                  -- #
+# --                                                                                   -- #
+# -- Some flags and options are mandatory - others are optional. Argument types        -- #
+# -- are usually => [ booleans, strings, lists, sets or numbers ].                     -- #
+# --                                                                                   -- #
+# -- --------------------------------------------------------------------------------- -- #
+# -- Art or Science                                                                    -- #
+# -- --------------------------------------------------------------------------------- -- #
+# --                                                                                   -- #
+# -- Parsing the command line and returning concise error messages is much more        -- #
+# -- [ART] than it is [SCIENCE]. This is because the permutations and combinations     -- #
+# -- are mind bogglingly vast. Hence this code is strictly ["best efforts"].           -- #
+# --                                                                                   -- #
+# -- That said, the invoked commands should be belt and braces in processing the       -- #
+# -- arguments and switches provided on the command line.                              -- #
+# --                                                                                   -- #
+# -- This command interpreter in no way absolves the evoked software from the legwork  -- #
+# -- of security, validation and semantic assessments.                                 -- #
+# --                                                                                   -- #
+# -- --------------------------------------------------------------------------------- -- #
+class CmdLine
+  include Singleton
+
+  attr_reader :create
+  attr_reader :task
+  attr_reader :do_read_db_names
+  attr_reader :do_register_user
+  attr_reader :do_destroy_app
+
+  attr_reader :key_values
+  attr_reader :args_cache
+  attr_reader :args_after
+
+
+  def initialize
+
+    # -- ----------------------------------------------------------- --- #
+    # -- If no commands to interpret - assume the caller needs help. --- #
+    # -- ----------------------------------------------------------- --- #
+    ARGV.push "--help" if ARGV.length == 0
+
+    @key_values = {}
+    @args_cache = [].replace ARGV
+
+    # --- ------------------------------------------------------------- --- #
+    # --- [--help] is a peripheral command with no [do] [what] pattern. --- #
+    # --- ------------------------------------------------------------- --- #
+    print_help_screen       if ARGV.include? "--help"
+    print_help_screen       if ARGV.include? "-h"
+
+    # --- -------------------------------------------------- --- #
+    # --- Each line below pertains to a [do] [what] command. --- #
+    # --- -------------------------------------------------- --- #
+    read_eco_create_args     if command_matches? "create", "what", "w"
+    read_read_db_names_args  if command_matches? "read", "s3", "s"
+    read_aws_register_args   if command_matches? "register", "aws-user", "a"
+    read_destroy_app_args    if command_matches? "destroy", "app", "a"
+    read_task_args           if command_matches? "task", "what", "w"
+
+    # --- --------------------------------------------------------- --- #
+    # --- Notify caller if [do] [what] portion could not be mapped. --- #
+    # --- --------------------------------------------------------- --- #
+    handle_cmd_match_fail  if @options_parser == nil
+
+    begin
+
+      @options_parser.parse!
+      @args_after = ARGV
+
+      missing_args = @mandatory_options.select{ |param| @key_values[param].nil? }
+      unless missing_args.empty?
+        raise OptionParser::MissingArgument.new(missing_args.join(', '))
+      end
+
+    rescue OptionParser::InvalidOption => exception
+
+      log.warn(ere) { "#--- ---------------------------------------------- --- #" }
+      log.warn(ere) { "#--- eco did not recognize a command option.        --- #" }
+      log.warn(ere) { "#--- ---------------------------------------------- --- #" }
+      log.warn(ere) { "#--- #{exception}" }
+      log.warn(ere) { "#--- #{exception.inspect}" }
+
+#### Fix this if too spurious
+#### Fix this if too spurious
+#### Fix this if too spurious
+#### Fix this if too spurious
+################      puts exception.backtrace if @@VERBOSE_MODE
+
+      log.warn(ere) { "#{exception.backtrace}" } ##### may be add if ARGV.include? "--debug"
+      log.warn(ere) { @options_parser.help }
+      log.warn(ere) { "#--- ---------------------------------------------- --- #" }
+
+      # @@
+      # @@ No need to exit from this - this script does not need
+      # @@ to be hard-coded with every command line option.
+      # @@ (We need only know the [Mandatory] ones which is
+      # @@ handled by the below rescue block.
+      # @@
+
+##################  DELETE ME ASAP
+##############      exit
+##################  DELETE ME ASAP
+
+
+    rescue OptionParser::MissingArgument => missing_arg
+
+      log.fatal(ere) { $!.to_s }
+      log.fatal(ere) { @options_parser }
+      exit
+
+    end
+
+  end
+
+
+  # --
+  # -- Returns true if the option text was included on the command line.
+  # --
+  # -- This method does not look within a list of values. Only call this
+  # -- method if the text is a free form switch WITHOUT an equal sign.
+  # --
+  def self.has? a_string
+    return CmdLine.instance.args_cache.include? a_string
+  end
+
+
+  # --
+  # -- Return true if symbol (switch) was included on the command line.
+  # --
+  # -- WARNING - Do not use externally as the line is cleared.
+  # --         - Call has? like =] if CmdLine.has? --debug
+  # --
+  def self.include? a_symbol
+    return CmdLine.instance.key_values.include? a_symbol
+  end
+
+
+  # -- ---------------------------------------------------------------------------- -- #
+  # -- Does the command line contain a specific command and a flag in either of its -- #
+  # -- forms - long and short. If yes then this method will return true.            -- #
+  # -- ---------------------------------------------------------------------------- -- #
+  def command_matches? cmd_str, flag_long, flag_short
+
+    return ( ARGV.include?( cmd_str ) && ARGV.include?("--#{flag_long}") ) ||
+       ( ARGV.include?( cmd_str ) && ARGV.include?("-#{flag_short}") )
+
+  end
+
+
+  # -- ---------------------------------------------------------------------------- -- #
+  # -- forms - long and short. If yes then this method will return true.            -- #
+  # -- ---------------------------------------------------------------------------- -- #
+  def handle_cmd_match_fail
+
+    log.fatal(ere) { "    # - ------------------------------------------------------------ - #" }
+    log.fatal(ere) { "    # - eco command ==> could not match == [do] [what] [how] [where] - #" }
+    log.fatal(ere) { "    # - ------------------------------------------------------------ - #" }
+    log.fatal(ere) { "    eco [do] [what]" }
+    log.fatal(ere) { "    Could not match the [do what] branch of the command tree." }
+    log.fatal(ere) { "    [do] is CRUD based eg [create, register, read, update, destroy]." }
+    log.fatal(ere) { "    The [what] part tells the command interpreter what you want to do." }
+    log.fatal(ere) { "    eco optional arguments == [how] [where] [to]" }
+    log.fatal(ere) { "    [how]   -   do it how   eg | --clean      | --dry-run |" }
+    log.fatal(ere) { "    [where] -   (on what)   eg | --cloud      | --local   |" }
+    log.fatal(ere) { "    [to]    -   do it to    eg | --eco-system | --service |" }
+
+    exit
+
+  end
+
+
+  ## --- --------------------------------------------------------- --- ##
+  ## --- How to use Declarative and Dynamic Command Interpretation --- ##
+  ## --- --------------------------------------------------------- --- ##
+  ## --- 
+  ## --- Once SREs are familiar with this command interpreter class
+  ## --- the next refactor step is to generate the whole thing dynamically.
+  ## --- I will probably write a ruby gem to do exactly this.
+  ## --- 
+  ## --- The essence is to create a JSON or YAML configuration file that
+  ## --- holds the command line interpretation variables. This is used to
+  ## --- dynamically generate the optparse blocks.
+  ## --- 
+  ## --- --------------------------------------------------------- --- ##
+  ## --- How to use Dynamically Generate the Help Screen           --- ##
+  ## --- --------------------------------------------------------- --- ##
+  ## --- 
+  ## --- To generate the help screen you can loop round calling each
+  ## --- parser block (without any actual cmd line arguments)!
+  ## --- 
+  ## --- Then you loop doing a to_string puts opt_parser for each
+  ## --- parser and all the options will be ejected automatically!
+  ## --- 
+  ## --- You are done when all read methods vanish (ruby magic)!
+  ## --- 
+  ## --- --------------------------------------------------------- --- ##
+
+
+  ## --- ---------------------- --- ##
+  ## --- Create the application --- ##
+  ## --- ---------------------- --- ##
+  def read_eco_create_args
+
+    ## ---------------------------------------------------------- #
+    @create = true
+    @mandatory_options = [:service_descriptors]
+    ## ---------------------------------------------------------- #
+    @options_parser = OptionParser.new do | the_options |
+
+      the_options.banner = "    eco create --what   => create which eco systems\n\n"
+
+##      the_options.on( "-f", "--versions-file FILE_PATH", "Service versions file in JSON (mandatory)") do | versions_file |
+
+##        @key_values[:versions_file] = versions_file
+
+##      end
+
+      the_options.on( "-w", "--what mongo,email,...", Array, "Comma separated service descriptors (mandatory)") do | service_descriptors_list |
+
+        @key_values[:service_descriptors] = service_descriptors_list
+
+      end
+
+    end
+
+  end
+
+
+  ## --- -------------------- --- ##
+  ## --- Register an AWS User --- ##
+  ## --- -------------------- --- ##
+  def read_aws_register_args
+
+    ## ---------------------------------------------------------- #
+    @do_register_user = true
+    @mandatory_options = [:aws_user, :aws_user_id, :aws_password]
+    ## ---------------------------------------------------------- #
+    @options_parser = OptionParser.new do | the_options |
+
+      the_options.banner = "    eco register --aws-user   => options to register [aws credentials]\n\n"
+
+      the_options.on( "-a", "--aws-user", "Registering AWS Credentials") do
+
+        @key_values[:aws_user] = true
+
+      end
+
+      the_options.on( "-u", "--aws-user-id AWS_USER_ID", "Your AWS User ID Key (mandatory)") do | aws_user_id |
+
+        @key_values[:aws_user_id] = aws_user_id
+
+      end
+
+      the_options.on( "-p", "--aws-password AWS_PASSWORD", "Your AWS User Password (mandatory)") do | aws_password |
+
+        @key_values[:aws_password] = aws_password
+
+      end
+
+    end
+
+  end
+
+
+  # --
+  # -- Task does something (encrypts or decrypts) some text.
+  # --
+  # --  main command  => encrypt
+  # --  mandatory arg => --text=abc123 or -t
+  # --
+  # --
+  def read_task_args
+
+    ## ------------------------------------------------------------------ #
+    @task = true
+    @mandatory_options = [:service_descriptors]
+    ## ------------------------------------------------------------------ #
+    @options_parser = OptionParser.new do | the_options |
+
+      the_options.banner = "    eco encrypt --text   => options to encrypt [some text]\n\n"
+
+
+      the_options.on( "-w", "--what mongo,email,...", Array, "Comma separated descriptors (mandatory)") do | service_descriptors_list |
+
+        @key_values[:service_descriptors] = service_descriptors_list
+
+      end
+
+
+      the_options.on( "-n", "--name NAME", "The name (reference) of the encryptee.") do | name |
+
+        @key_values[:name] = name
+
+      end
+
+      the_options.on( "-f", "--file FILE", "The name of the file whose text is to be decrypted") do | file |
+
+        @key_values[:file] = file
+
+      end
+
+    end
+
+  end
+
+
+  ## --- -------------------------- --- ##
+  ## --- Read the DB Name Arguments --- ##
+  ## --- -------------------------- --- ##
+  def read_read_db_names_args
+
+    ## ---------------------------------------------------------- #
+    @do_read_db_names = true
+    @mandatory_options = [:read_db_names]
+    ## ---------------------------------------------------------- #
+    @options_parser = OptionParser.new do | the_options |
+
+      the_options.banner = "    eco read --s3   => reading names of customer databases in S3\n\n"
+
+      the_options.on( "-s", "--s3", "Available Customer DBs in S3") do
+
+        @key_values[:read_db_names] = true
+
+      end
+
+    end
+
+  end
+
+
+  ## --- -------------------------------------------------------- --- ##
+  ## --- Destroy and reclaim resources from created applications. --- ##
+  ## --- -------------------------------------------------------- --- ##
+  def read_destroy_app_args
+
+    ## ---------------------------------------------------------- #
+    @do_destroy_app = true
+    @mandatory_options = [:destroy_app, :key]
+    ## ---------------------------------------------------------- #
+    @options_parser = OptionParser.new do | the_options |
+
+      the_options.banner = "    eco destroy --app   => destroying an eco system\n\n"
+
+      the_options.on( "-a", "--app", "Destroy enterprise application") do
+
+        @key_values[:destroy_app] = true
+
+      end
+
+      the_options.on( "-k", "--key APP_KEY", "Key (ref) of app to delete (mandatory)") do | key_value |
+
+        @key_values[:key] = key_value
+
+      end
+
+    end
+
+  end
+
+
+  ## --- --------------------------------------------------------- --- ##
+  ## --- How to use Declarative and Dynamic Command Interpretation --- ##
+  ## --- --------------------------------------------------------- --- ##
+  ## --- 
+  ## --- Once SREs are familiar with this command interpreter class
+  ## --- the next refactor step is to generate the whole thing dynamically.
+  ## --- I will probably write a ruby gem to do exactly this.
+  ## --- 
+  ## --- The essence is to create a JSON or YAML configuration file that
+  ## --- holds the command line interpretation variables. This is used to
+  ## --- dynamically generate the optparse blocks.
+  ## --- 
+  ## --- --------------------------------------------------------- --- ##
+  ## --- How to use Dynamically Generate the Help Screen           --- ##
+  ## --- --------------------------------------------------------- --- ##
+  ## --- 
+  ## --- To generate the help screen you can loop round calling each
+  ## --- parser block (without any actual cmd line arguments)!
+  ## --- 
+  ## --- Then you loop doing a to_string puts opt_parser for each
+  ## --- parser and all the options will be ejected automatically!
+  ## --- 
+  ## --- --------------------------------------------------------- --- ##
+
+  def print_help_screen
+
+    read_eco_create_args
+    args_documented = @options_parser.to_s
+    read_aws_register_args
+    args_documented = "#{args_documented}\n\n#{@options_parser.to_s}"
+    read_read_db_names_args
+    args_documented = "#{args_documented}\n\n#{@options_parser.to_s}"
+    read_destroy_app_args
+    args_documented = "#{args_documented}\n\n#{@options_parser.to_s}"
+
+    if false then
+      log.warn(ere) { "    # --- --------------------------------------------------------------------- --- #" }
+      log.warn(ere) { "    # --- create executable  => =>  [only for DevOps and SRE personnel]         --- #" }
+      log.warn(ere) { "    # --- --------------------------------------------------------------------- --- #" }
+
+      log.warn(ere) { "        ruby eco-invoke.rb [do] [what]" }
+      log.warn(ere) { "        ruby eco-invoke.rb [create] [--exe]" }
+      log.warn(ere) { "        ruby eco-invoke.rb create --exe" }
+    end
+
+    log.warn(ere) { "    # --- --------------------------------------------------------------------- --- #" }
+    log.warn(ere) { "    # --- eco peripheral commands                                               --- #" }
+    log.warn(ere) { "    # --- --------------------------------------------------------------------- --- #" }
+    log.warn(ere) { "        eco --help" }
+    log.warn(ere) { "        eco -h" }
+    log.warn(ere) { "    # --- --------------------------------------------------------------------- --- #" }
+    log.warn(ere) { "    # --- eco arguments documentation                                           --- #" }
+    log.warn(ere) { "    # --- --------------------------------------------------------------------- --- #" }
+    log.warn(ere) { args_documented }
+
+    exit
+
+  end
+
+
+  # -- -------------------------------------------------------- #
+  # -- [Cold Call Pattern]                                   -- #
+  # --    If class has no [internal] dependencies it can     -- #
+  # --    initialize itself ignoring any require order.      -- #
+  # --                                                       -- #
+  # -- [Advantage of Cold Call Pattern]                      -- #
+  # --    The class [dependency] is not [hardcoded] into     -- #
+  # --    any other class. Others benefit from initialize    -- #
+  # --    activities without a create / handshake call.      -- #
+  # --                                                       -- #
+  # -- -------------------------------------------------------- #
+  CmdLine.instance
+
+
+end

data/lib/opensecret/commons/eco.faculty.rb

@@ -0,0 +1,364 @@
+#!/usr/bin/ruby
+	
+# --
+# -- eco-system [provisioning] begins in earnest here. By making
+# -- a [super] call (at the beginning, middle or end) - eco-systems
+# -- can extend the functionality provided here.
+# --
+# -- To prevent this code running, child classes must provide their
+# -- own provision along an (optional) alternative implementation.
+# --
+class EcoFaculty
+
+  attr_reader :eco_id_str
+
+  #--
+  #-- Get the folder path to the eco-system [plugin]
+  #-- source directory.
+  #--
+  #-- Also see the plugin runtime directory which is
+  #-- the runtime folder created by the method named
+  #-- => EcoFaculty.instantiate_runtime
+  #--
+  #-- -------------
+  #-- Dependency
+  #-- -------------
+  #--
+  #-- The method :core_provisioning in the plugin must
+  #-- exist and must have been "Required".
+  #--
+  def plugin_src_dir
+
+    return File.dirname self.method(:core_provisioning).source_location.first
+
+  end
+
+
+  # --
+  # -- Facts are the business of this eco-system behaviour class.
+  # -- This provision method will collect the eco-system plugin id
+  # -- and from that assimilate all known fact files.
+  # --
+  def provision
+
+    @eco_id_str = SnapFlat.do self.class.name
+    @eco_id_sym = @eco_id_str.gsub(".", "_").to_sym
+    @plugin_path = plugin_src_dir
+
+    FactTree.instance.instantiate @eco_id_str, @plugin_path
+    FactTree.instance.assimilate_instance_facts
+
+    instantiate_runtime FactTree.instance.f
+
+    FactTree.instance.identify_my_workstation
+    FactTree.instance.assimilate_station_facts
+    FactTree.instance.assimilate_plugin_facts
+    FactTree.instance.assimilate_general_facts
+
+    @c = FactTree.instance.f
+    @i = FactTree.instance.i
+    @p = FactTree.instance.f[@eco_id_sym]
+
+    # --
+    # -- assimilate and configure aws cloud credentials
+    # -- if the plugin fact [aws.creds.dir] exists.
+    # --
+    configure_aws_credentials if @c[:aws][:creds_exist?]
+
+  end
+
+
+  # --
+  # -- Assimilate and configure aws cloud credentials.
+  # -- Call this method only when it is certain that the
+  # -- hub fact [aws.creds.dir] exists.
+  # --
+  # -- By convention this method expects the decrypted
+  # -- AWS user credential INI file to be inside the above
+  # -- dir with name <<plugin.id>>.aws.credentials.ini
+  # --
+  def configure_aws_credentials
+
+    # --
+    # -- Before the rubber can hit the road - we must
+    # -- first read in the secret credentials. To avoid
+    # -- logging the secrets we read it up into its own
+    # -- isolated mini fact database.
+    # --
+    # -- The aws creds database lives just long enough
+    # -- to programmatical configure the AWS IAM user.
+    # --
+    FactTree.instance.assimilate_ini_file @c[:aws][:creds_path]
+    aws_creds = FactTree.instance.f
+    log.info(ere) { "AWS Region Key => #{aws_creds[@eco_id_sym][:aws_region_key]}" }
+
+    # --
+    # -- Now the rubber can hit the road and we configure
+    # -- the AWS Ruby SDK with the IAM credentials that
+    # -- have been recovered.
+    # --
+    Aws.use_bundled_cert!
+    Aws.config.update({
+      :access_key_id     => aws_creds[@eco_id_sym][:aws_access_key],
+      :secret_access_key => aws_creds[@eco_id_sym][:aws_secret_key],
+      :region            => aws_creds[@eco_id_sym][:aws_region_key]
+    })
+
+    # --
+    # -- Temporarily add the AWS credentials to the environment
+    # -- variables so that infrastructure provisioning tools like
+    # -- Terraform can access the cloud cedentials.
+    # --
+    EnvVar.new.write_env_var "AWS_ACCESS_KEY_ID",     aws_creds[@eco_id_sym][:aws_access_key]
+    EnvVar.new.write_env_var "AWS_SECRET_ACCESS_KEY", aws_creds[@eco_id_sym][:aws_secret_key]
+    EnvVar.new.write_env_var "AWS_DEFAULT_REGION",    aws_creds[@eco_id_sym][:aws_region_key]
+
+  end
+
+
+  # --
+  # -- This key (instantiation) behaviour
+  # --
+  # --  1 - [CREATES] the runtime plugin folder [then]
+  # --  2 - [COPIES]  into it files from the plugin source folder [and]
+  # --  3 - [NOTIFY]  (point) log utility to new (plugin dir) logfile
+  # --
+  # -- Before continuing the fact assimilation process we now
+  # -- know enough to instantiate the plugin runtime folder and
+  # -- start logging to a file within it.
+  # --
+  def instantiate_runtime core_db
+
+    Throw.if_exists core_db[:runtime][:dir]
+
+    # --
+    # -- Create the new runtime directory then
+    # -- Copy asset templates into it.
+    # -- Note that these templates contain unresolved fact directives.
+    # --
+    FileUtils.mkdir_p core_db[:runtime][:dir] unless File.exists? core_db[:runtime][:dir]
+    FileUtils.copy_entry @plugin_path, core_db[:runtime][:dir]
+    FactTree.instance.add_dir_to_identity core_db[:runtime][:dir]
+
+    # --
+    # -- Evaluate the absolute [logfile path] within
+    # -- the eco system instance runtime directory.
+    # --
+    # -- Then tell the logging.rb MIXIN that the new logfile
+    # -- at (logfile_path) is ready to be used.
+    # -- This MIXIN affects all classes that have log write statements
+    # --
+    logfile_path = File.join core_db[:runtime][:dir], "#{core_db[:runtime][:dirname]}.log"
+    log.info(ere) { "[LAST] - The last logging statement going to STDOUT but NOT logfile." }
+    set_logfile_path logfile_path
+    log.info(ere) { "[FIRST] - The first log going to [both] STDOUT and a logfile." }
+    log.info(ere) { "logfile => #{logfile_path}" }
+    log.info(ere) { "Log Level is now set @ => #{log.level.to_s}" }
+
+  end
+
+
+  # --
+  # -- Write the entirery of command line options into
+  # -- the fact database as an array.
+  # --
+  # --  Group Symbol => :cmd_line
+  # --  Key Symbol   => :options
+  # --  Value Type   => (Array of Strings)
+  # --
+####  def read_cmdline_facts
+
+####    puts
+####    puts "# -- ------------------ -------------------------- --- "
+####    puts "# -- Command Line Facts -------------------------- --- "
+####    puts "# -- ------------------ -------------------------- --- "
+####    pp CmdLine.instance.args_cache
+####    puts "# -- ------------------ -------------------------- --- "
+####    puts
+
+####    @fact_db.add_fact :cmd_line, :options, CmdLine.instance.args_cache
+
+####  end
+
+
+  # --
+  # -- Scan every file in the eco plugin directory in search of
+  # -- fact placeholder keys contained in the fact database.
+  # --
+  # -- Once found, replace them with the corresponding value.
+  # --
+  # -- -----------
+  # -- Warning
+  # -- -----------
+  # -- This behaviour is [NOT RECURSIVE].
+  # -- Only files in the folder are examined.
+  # -- Folders in the folder are ignored.
+  # --
+  def replace_placeholders
+
+    Files.find_replace Refactor.flatten(@c), @c[:runtime][:dir]
+
+  end
+
+
+  ## --- ---------------------------------------------- --- #
+  ## --- Return the factthat is                         --- #
+  ## ---   [1] under the current eco plugin banner      --- #
+  ## ---   [2] has the key symbol in the parameter      --- #
+  ## --- ---------------------------------------------- --- #
+  def get_eco_fact key_symbol
+    error_msg = "fact 4 group => #{@eco_id_sym} + key => #{key_symbol} not in db."
+    raise ArgumentError.new "\n\n#{error_msg}\n\n" unless eco_fact_exists? key_symbol
+    return @c[@eco_id_sym][key_symbol]
+  end
+
+
+  ## --- ---------------------------------------------- --- #
+  ## --- Return the fact that is                        --- #
+  ## ---   [1] under the current eco plugin banner      --- #
+  ## ---   [2] has the key symbol in the parameter      --- #
+  ## --- ---------------------------------------------- --- #
+  def e_fact key_symbol
+    error_msg = "fact 4 group => #{@eco_id_sym} + key => #{key_symbol} not in db."
+    raise ArgumentError.new "\n\n#{error_msg}\n\n" unless eco_fact_exists? key_symbol
+    return @c[@eco_id_sym][key_symbol]
+  end
+
+
+  ## --- ---------------------------------------------- --- #
+  ## --- Return the fact that is                        --- #
+  ## ---   [1] under the current eco plugin banner      --- #
+  ## ---   [2] has the key symbol in the parameter      --- #
+  ## --- ---------------------------------------------- --- #
+  def plugin_fact key_symbol
+    error_msg = "fact 4 group => #{@eco_id_sym} + key => #{key_symbol} not in db."
+    raise ArgumentError.new "\n\n#{error_msg}\n\n" unless eco_fact_exists? key_symbol
+    return @c[@eco_id_sym][key_symbol]
+  end
+
+
+  # --
+  # -- Return [true] if a fact exists that is
+  # --
+  # --    [1] under the banner of the current plugin id
+  # --    [2] with a key symbol matching the parameter
+  # --    [3] is neither empty nor solely whitespace
+  # --
+  def plugin_fact_exists? key_symbol
+    return db_fact_exists? @eco_id_sym, key_symbol
+  end
+
+
+  ## --- ------------------------------------------------------ --- #
+  ## --- Return [true] if a fact exists that is                 --- #
+  ## ---   [1] under the banner of the current plugin id        --- #
+  ## ---   [2] with a key symbol matching the parameter         --- #
+  ## ---   [3] is neither empty nor solely whitespace           --- #
+  ## --- ------------------------------------------------------ --- #
+  def eco_fact_exists? key_symbol
+    return db_fact_exists? @eco_id_sym, key_symbol
+  end
+
+
+  ## --- ---------------------------------------------------------- --- #
+  ## --- Return [true] if a fact exists that                        --- #
+  ## ---   [1] DOES NOT ASSUME FACT IS A STRING
+  ## ---   [1] carries the primary symbol key in 1st parameter      --- #
+  ## ---   [2] carries the secondary symbol key in 2nd parameter    --- #
+  ## ---   [3] is neither empty nor solely whitespace               --- #
+  ## --- ---------------------------------------------------------- --- #
+  def db_fact_exists? group_symbol, key_symbol
+    return false unless @c.has_key? group_symbol
+    fact_value = @c[group_symbol][key_symbol]
+    return !fact_value.nil?
+  end
+
+
+  ## ---   [1] ASSUMES THAT FACT IS A STRING      --- #
+  def string_fact_exists? group_symbol, key_symbol
+    return false unless @c.has_key? group_symbol
+    fact_value = @c[group_symbol][key_symbol]
+    return false if fact_value.nil?
+    return fact_value.strip.length > 0
+  end
+
+
+  # --
+  # -- If eco plugins wish to update only [SOME] of the properties
+  # -- within [application.properties] then they should set
+  # --
+  # --   fact key => @c[@c[:plugin][:id]][:props_src_path]
+  # --   fact val => "/path/to/application.properties
+  # --
+  # -- The property file will be assimilated and the key / value
+  # -- pairs will be attached under the :app_properties grouping
+  # -- symbol. One o more facts can be updated (overwritten) and
+  # -- later written back (see write_app_properties)
+  # --
+  def read_properties
+
+    return unless eco_fact_exists? :props_src_path
+    @fact_db.assimilate_property_file e_fact(:props_src_path), :app_properties
+
+  end
+
+
+  # --
+  # -- If eco plugins wish the properties in the database under
+  # -- :app_properties to be written to create (or overwrite)
+  # -- the app properties they should create
+  # --
+  # --   fact key => @c[@c[:plugin][:id]][:props_dst_dirs]
+  # --   fact val => "/path/to/application.properties
+  # -- 
+  # -- ----------------
+  # -- Warning (Array)
+  # -- ----------------
+  # -- The [:props_dst_dirs] fact is an [ARRAY].
+  # -- The same property key/value pairs will be serialized into
+  # -- each file url stated in the array. The [:props_dst_dirs]
+  # -- is (in contrast) a simple single filename.
+  # -- 
+  # -- -----------------------------
+  # -- (Optional) - Src Properties
+  # -- -----------------------------
+  # -- Plugins do not need to set the :app_props_src_path key.
+  # -- If they only set the (dst) key, any properties set in the
+  # -- fact database will still be written out.
+  # --
+  def write_properties
+  
+    return unless eco_fact_exists? :props_dst_dirs
+    property_files = e_fact :props_dst_dirs
+
+    property_files.each do | property_dir |
+
+      Dir.mkdir property_dir unless File.exists? property_dir
+      Files.write_properties(
+        @c[:app_properties],
+        property_dir,
+        e_fact(:props_dst_name)
+      )
+
+    end
+
+  end
+
+
+  def read_block_facts module_path, method_name, grp_sym, key_sym, key_val
+
+    # -- ---------------------------------------------------------- -- #
+    # -- Derive name of block db ini file using id and method name. -- #
+    # -- ---------------------------------------------------------- -- #
+    block_filepath = FactLocator.block_factdb_path module_path, method_name
+    Throw.if_not_exists block_filepath
+
+    # -- ----------------------------------------------------------- -- #
+    # -- Initialize block database building upon the wider scoped @e -- #
+    # -- ----------------------------------------------------------- -- #
+    FactReader.new @c, block_filepath, grp_sym, key_sym, key_val
+
+  end
+
+
+end