opensecret 0.0.951 → 0.0.957

data/lib/version.rb

@@ -1,3 +1,3 @@
 module OpenSecret
-  VERSION = "0.0.951"
+  VERSION = "0.0.957"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: opensecret
 version: !ruby/object:Gem::Version
-  version: 0.0.951
+  version: 0.0.957
 platform: ruby
 authors:
 - Apollo Akora
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-02-26 00:00:00.000000000 Z
+date: 2018-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: inifile
@@ -117,24 +117,12 @@ files:
 - lib/logging/gem.logging.rb
 - lib/notepad/blow.rb
 - lib/opensecret.rb
-- lib/opensecret/commons/eco.faculty.rb
-- lib/opensecret/commons/eco.system.rb
-- lib/opensecret/commons/eco.systems.rb
 - lib/opensecret/executors/crypt.keys/crypt.keys.ini
 - lib/opensecret/executors/crypt.keys/crypt.keys.rb
 - lib/opensecret/executors/decrypt/decrypt.ini
 - lib/opensecret/executors/decrypt/decrypt.rb
 - lib/opensecret/executors/encrypt/encrypt.ini
 - lib/opensecret/executors/encrypt/encrypt.rb
-- lib/opensecret/factbase/hub-runtime.ini
-- lib/opensecret/factbase/known-hosts.ini
-- lib/opensecret/factbase/published.facts/blobbolicious-facts.ini
-- lib/opensecret/factbase/published.facts/credential-facts.ini
-- lib/opensecret/factbase/published.facts/infrastructure-facts.ini
-- lib/opensecret/factbase/readme.md
-- lib/opensecret/factbase/retired.facts/maven.database.ide.facts.ini
-- lib/opensecret/factbase/retired.facts/s3-upload-block-facts.ini
-- lib/opensecret/plugins.io/file/file.rb
 - lib/opensecret/plugins.io/git/git.flow.rb
 - lib/plugins/cipher.rb
 - lib/plugins/ciphers/aes-256.rb
@@ -142,12 +130,15 @@ files:
 - lib/plugins/stores/store.rb
 - lib/plugins/usecase.rb
 - lib/plugins/usecases/init.rb
-- lib/plugins/usecases/on.rb
+- lib/plugins/usecases/lock.rb
 - lib/plugins/usecases/open.rb
+- lib/plugins/usecases/put.rb
 - lib/plugins/usecases/safe.rb
 - lib/session/attributes.rb
+- lib/session/dictionary.rb
 - lib/session/fact.finder.rb
 - lib/session/require.gem.rb
+- lib/session/session.rb
 - lib/session/time.stamp.rb
 - lib/session/user.home.rb
 - lib/using.txt

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

@@ -1,364 +0,0 @@
-#!/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

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

@@ -1,437 +0,0 @@
-#!/usr/bin/ruby
-	
-# --- --------------------------------------------------------------------------------------- -- #
-# --- Build the [services eco-system]. The app sits at the centre of the services eco-system. -- #
-# --- Everything that is done -> is done for (because of, to, in spite of) the [application]. -- #
-# --- --------------------------------------------------------------------------------------- -- #
-# --- --------------------------------------------------------------------------- --- #
-# --- The [eco service folder] contains the templates, scripts and configuration. --- #
-# --- By convention the folder name (off prj root) matches the name of the class. --- #
-# --- --------------------------------------------------------------------------- --- #
-# --- Example => ProvisionMongoDb assets are provision.mongo.db                   --- #
-# --- --------------------------------------------------------------------------- --- #
-# --- By Convention                                                               --- #
-# ---                Ruby Class => EcoAppServer                             --- #
-# ---          is Found in File => eco.system.plugins/eco.app.server.rb     --- #
-# ---             Has Assets in => provision.app.server/                          --- #
-# ---         and Inherits from => ProvisionEcoService                            --- #
-# ---             Found in File => provision.services/provision.eco.service.rb    --- #
-# --- --------------------------------------------------------------------------- --- #
-class EcoSystem
-
-  # -- -------------------------------------------------------------- -- #
-  # -- 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.  -- #
-  # -- -------------------------------------------------------------- -- #
-  def provision
-
-    super
-
-    pre_provisioning      # --> Do work to gather key provisioning facts
-    replace_placeholders  # --> Replace key facts in files within the eco folder
-
-    core_provisioning     # --> Do the heavy lifting 4 provisioning the eco service
-
-    overwrite_lines       # --> Replace pinpointed lines that include a string set.
-    replace_placeholders  # --> Replace xtra key facts to prep 4 post provisioning.
-    post_provisioning     # --> Notifying service dependents is usually done here.
-
-  end
-
-  ## --- ----------------------------------------------------------------------------- --- #
-  ## --- Provision the services eco-system (universe) with the app as the focal point. --- #
-  ## --- ----------------------------------------------------------------------------- --- #
-  def pre_provisioning
-
-    read_properties
-    inject_reusables
-
-  end
-
-
-  # --
-  # -- Implements service discovery for the provisioned eco-system services.
-  # --
-  def post_provisioning
-
-    execute_scripts
-    s3_upload
-    s3_synchronize
-    write_properties
-    sync_2s3_bucket
-
-  end
-
-
-  #--
-  #-- Get eco-system reusable directory filepaths within
-  #-- an array.
-  #--
-  #-- The two known directories are
-  #--
-  #--   [1] - reusable.scripts
-  #--   [2] - reusable.templates
-  #--
-  #--
-  def self.reusable_buckets
-
-    project_basedir = File.dirname( File.dirname( __FILE__ ) )
-    reusable_buckets = Array.new
-
-    reusable_buckets.push( File.join(project_basedir, "reusable.scripts") )
-    reusable_buckets.push( File.join(project_basedir, "reusable.templates") )
-
-    return reusable_buckets
-
-  end
-
-
-  # --
-  # -- Gather the reusable [file] resources from the directoy bucket
-  # -- arrays that are declared to hold these assets.
-  # --
-  # -- The reusables are gathered only if the plugin declares a fact
-  # -- called [:reusables] that is an array of simple filenames.
-  # --
-  # -- This method does a recursive search to find and then copy over
-  # -- these reusable files into the runtime directory.
-  # --
-  # -- ------------------------------
-  # -- Constraint - Duplicate Names
-  # -- ------------------------------
-  # --
-  # -- Duplicate asset filenames introduce ambiguity in as far as
-  # -- reusable assets are concerned. Therefore an error will be
-  # -- raised if this situation arises.
-  # --
-  def inject_reusables
-
-    return unless eco_fact_exists?(:inventory) || eco_fact_exists?(:runnables)
-    files_map = Files.in_folders EcoSystem.reusable_buckets
-    reusables = e_fact(:inventory).merge( e_fact(:runnables) )
-    reusables.each do |source_name, target_name|
-
-      error_1 = "Cannot find reusable [#{source_name}].\n\n#{files_map.inspect}"
-      raise ArgumentError.new error_1 unless files_map.has_key? source_name
-      log.info(ere) {"Copying reusable #{source_name} => to => #{target_name}"}
-      source_file = File.join files_map[source_name], source_name
-      target_file = File.join @c[:runtime][:dir], target_name
-      log.info(ere) {"Source DevOps Asset => #{nickname source_file}"}
-      log.info(ere) {"Target DevOps Asset => #{nickname target_file}"}
-
-      FileUtils.cp source_file, target_file
-
-    end
-
-  end
-
-
-  # --
-  # -- Use the remote host instantiated for the eco plugin.
-  # -- Upload the plugin folder and run the reusables.
-  # --
-  def execute_scripts
-
-    return unless eco_fact_exists? :runnables
-
-    log.info(ere) { "[collate] ---------------------------------------- --- #" }
-    log.info(ere) { "[collate] collate will upload and execute scripts. --- #" }
-    log.info(ere) { "[collate] ---------------------------------------- --- #" }
-    log.info(ere) { "#{pp e_fact(:runnables).values}" }
-    log.info(ere) { "[collate] ---------------------------------------- --- #" }
-
-    install_dos2unix = "sudo apt-get install -y dos2unix"
-    plugin_host = @c[:machine][:host_class]
-    plugin_host.runtime_dir = @c[:runtime][:dir]
-
-    plugin_host.execute_cmd install_dos2unix
-    plugin_host.upload_folder @c[:runtime][:dstname], @c[:runtime][:dir]
-
-
-    e_fact(:runnables).each_value do | script_name |
-
-      script_path =  @c[:runtime][:dstname] + "/" + @c[:runtime][:dirname] + "/" + script_name
-
-      cmd1 = "chmod u+x " + script_path
-      cmd2 = "dos2unix " + script_path
-      cmd3 = script_path
-
-####      plugin_host.execute_ansible_cmd @c[:runtime][:dir]
-####      exit
-
-
-      plugin_host.execute_cmd cmd1
-      plugin_host.execute_cmd cmd2
-      plugin_host.execute_cmd cmd3
-
-    end
-
-    plugin_host.log_remote_host
-
-  end
-
-
-  # -- ----------------------------------------------------- -- #
-  # -- sync folder with s3 bucket under certain conditions.  -- #
-  # -- ----------------------------------------------------- -- #
-  # -- Sync Conditions                                       -- #
-  # -- ----------------------------------------------------- -- #
-  # --   [1] - running in a unix environment                 -- #
-  # --   [2] - key [s3sync.bucket.name] exists               -- #
-  # --   [3] - key [s3sync.path.offset] exists               -- #
-  # --   [4] - s3 bucket exists and is writeable             -- #
-  # --   [5] - local dir exists and is readable              -- #
-  # --                                                       -- #
-  # -- ----------------------------------------------------- -- #
-  # -- Dependencies and Assumptions                          -- #
-  # -- ----------------------------------------------------- -- #
-  # --   the aws iam environment variables are set           -- #
-  # --   the s3 bucket specified exists and is writable      -- #
-  # --   the s3 bucket contents are deletable                -- #
-  # --   local path offset off [plugin folder] exists        -- #
-  # --   the [awscli] apt-get package is installed           -- #
-  # -- ----------------------------------------------------- -- #
-  def s3_synchronize
-
-    return if Gem.win_platform?
-    return unless eco_fact_exists? :s3sync_bucket
-    return unless eco_fact_exists? :s3sync_folder
-
-    log.info(ere) { "[s3 sync] -------------------------------------------- --- #" }
-    log.info(ere) { "[s3 sync] eco plugin running on a non-windows platform --- #" }
-    log.info(ere) { "[s3 sync] with s3 sync parameters available.           --- #" }
-    log.info(ere) { "[s3 sync] -------------------------------------------- --- #" }
-
-    AwsS3.instance.log_bucket_summary
-    AwsS3.instance.sync_with_s3 e_fact(:s3sync_bucket), e_fact(:s3sync_folder)
-    AwsS3.instance.log_bucket_summary
-
-  end
-
-
-  # --
-  # -- [SYNC] a local folder with a given S3 bucket at a particular
-  # -- folder offset location, with a specific set of sync options.
-  # --
-  # -- This behaviour is driven by a (plugin.id).s3.sync.spec.json
-  # -- specification file that states
-  # --
-  # --   [1] - the source folder whose contents will be sync'd up
-  # --   [2] - the S3 bucket name into which to sync the contents
-  # --   [3] - the S3 folder path offset (within the S3 bucket)
-  # --   [4] - sync options like delete, size-only, acl and more
-  # --
-  def sync_2s3_bucket
-
-    return unless @c.has_key?(:s3_sync) && File.exists?(@c[:s3_sync][:spec_filepath])
-
-    AwsS3.instance.log_bucket_summary
-
-    sync_directives = JSON.parse(
-      File.read(@c[:s3_sync][:spec_filepath]),
-      object_class: OpenStruct
-    )
-
-    sync_directives.each do | sync_directive |
-
-      log.info(ere) { "[sync] ############################################################### ### #" }
-      log.info(ere) { "[sync] --------------------------------------------------------------- --- #" }
-      log.info(ere) { "[sync] sync-ing local folder to s3 bucket [#{sync_directive.s3_bucket_name}]" }
-      log.info(ere) { "[sync] --------------------------------------------------------------- --- #" }
-      log.info(ere) { "[sync] sync source folder => #{sync_directive.local_folder}" }
-      log.info(ere) { "[sync] source bucket name => #{sync_directive.s3_bucket_name}" }
-      log.info(ere) { "[sync] mirror bucket name => #{sync_directive.bucket_b4_name}" }
-      log.info(ere) { "[sync] bucket offset path => #{sync_directive.offset_path}" }
-      log.info(ere) { "[sync] sync options array => #{sync_directive.sync_options}" }
-      log.info(ere) { "[sync] --------------------------------------------------------------- --- #" }
-
-      # --
-      # -- Is it worthwhile to copy between S3 buckets first
-      # -- before sync-ing up the local folder?
-      # --
-      # -- We deem it yes if (and only if)
-      # --
-      # --    a) the to-sync folder is over [10MB]
-      # --    b) a bucket_b4_name has been specified
-      # --    c) the folder to sync does [NOT] exist.
-      # --    d) the b4 folder [DOES] exist.
-      # --
-      # -- If so a S3 [bucket] to [bucket] mirror/copy may
-      # -- dramatically reduce sync time.
-      # --
-      AwsS3.instance.copy_folder_between_buckets(
-        sync_directive.bucket_b4_name,
-        sync_directive.s3_bucket_name,
-        sync_directive.offset_path
-      ) if copy_b4_sync_worthwhile?( sync_directive )
-
-
-      AwsS3.instance.sync_local_to_s3(
-        sync_directive.local_folder,
-        sync_directive.s3_bucket_name,
-        sync_directive.offset_path,
-        sync_directive.sync_options
-      )
-
-    end
-
-    AwsS3.instance.log_bucket_summary
-
-  end
-
-
-  # --
-  # -- [COPY] from another s3 bucket [B4 SYNC] if [WORTHWHILE]
-  # --
-  # -- Once a month (or week) performance may be gained by copying
-  # -- from the previous s3 bucket before sync-ing the local folder.
-  # --
-  # -- The first [backup] of the new month/week/day is a full backup
-  # -- of a local folder to up-sync. This can take a lot of time for
-  # -- a say [7Gig] folder holding many little files.
-  # --
-  # -- -------------------
-  # -- S3 to S3 Mirror
-  # -- -------------------
-  # -- If we copy (mirror) the previous S3 bucket folder before the
-  # -- sync we gain much in performance because S3 to S3 copying is
-  # -- super fast - then just the delta is sync'd up.
-  # --
-  # -- -------------------------------
-  # -- Pre-Conditions - Copy B4 Sync
-  # -- -------------------------------
-  # --
-  # -- They copy/mirror before sync will occur when the
-  # --
-  # --   1 - [sync_options.copy_b4_sync_if] flag is [true]
-  # --   2 - to sync S3 folder (not bucket) does NOT exist
-  # --   3 - previous periods (month/week..) folder exists
-  # --
-  # -- -------------
-  # -- Assumptions
-  # -- -------------
-  # -- Currently assumes the period is ALWAYS [monthly].
-  # -- Change this to cater for
-  # --   [ hourly, daily, weekly, monthly, quarterly, yearly ]
-  # --
-  def copy_b4_sync_worthwhile? sync_attr
-
-    return false if sync_attr.bucket_b4_name.nil?
-
-    sync_folder_exists =
-      AwsS3.instance.bucket_folder_contains_something?(
-        sync_attr.s3_bucket_name,
-        sync_attr.offset_path
-      )
-
-    return false if sync_folder_exists
-
-    b4_folder_exists =
-      AwsS3.instance.bucket_folder_contains_something?(
-        sync_attr.bucket_b4_name,
-        sync_attr.offset_path
-      )
-
-    return b4_folder_exists
-
-  end
-
-
-  # --- ---------------------------------------------------------------------------- --- #
-  # --- Any file in the eco folder whose name starts with [:s3][:upload_prefix] gets --- #
-  # --- uploaded to the S3 provisioning folder (in monthly bucket). Then the url     --- #
-  # --- is written into the app properties database with a key that is the remaining --- #
-  # --- filename after the preceeding s3 prefix is removed and subsequently appended --- #
-  # --- appended with the string ".url"                                              --- #
-  # --- ---------------------------------------------------------------------------- --- #
-  def s3_upload
-
-    log.info(ere) { "[s3 upload] examing files in #{@c[:runtime][:dir]}" }
-
-    # -- ------------------------------------------------------------------ -- #
-    # -- Scan folder for files whose names begin with the s3 upload prefix. -- #
-    # -- ------------------------------------------------------------------ -- #
-    Dir.foreach( @c[:runtime][:dir] ) do | file_name |
-
-      file_path = File.join @c[:runtime][:dir], file_name
-      next if File.directory? file_path
-      next unless file_name.start_with? @c[:s3][:upload_prefix]
-
-      read_block_facts __FILE__, __method__, :upload, :src_file_name, file_name
-      Dir.mkdir @c[:s3][:uploads_dir] unless File.exists? @c[:s3][:uploads_dir]
-      next if File.exists? @c[:upload][:dst_file_path]
-      
-      FileUtils.cp @c[:upload][:src_file_path], @c[:upload][:dst_file_path]
-
-      AwsS3.instance.log_bucket_summary
-
-      log.warn(ere) { "Warning - Not uploading to S3 bucket = File ==| #{@c[:upload][:dst_file_path]}" }
-      log.warn(ere) { "Warning - Not adding S3 resource URL fact to app_properties fact group." }
-##### === =============================================================================================
-##### === Commenting this prevents uploading any file with the s3put tag.
-##### === =============================================================================================
-##### ===      s3_url = AwsS3.instance.upload_to_s3 @c[:s3][:bucket_name], @c[:upload][:dst_file_path]
-##### ===      @c.add_fact :app_properties, @c[:upload][:app_props_key], s3_url
-##### === =============================================================================================
-
-    end
-
-  end
-
-  
-  # --
-  # -- [FIND] lines that include a set of configured strings and
-  # -- [REPLACE] then with the configured alternative.
-  # --
-  # -- This behaviour is driven by a (plugin.id).line.replace.json
-  # -- configuration file that states
-  # --
-  # --   [1] - the target file to change
-  # --   [2] - the array of words to match each line against
-  # --   [3] - new line replacing old if all the words match
-  # --
-  # -- -----------------------------------
-  # -- [Pre-Conditions] => Only act when
-  # -- -----------------------------------
-  # --
-  # --   1. plugin dir has a json [targetting] configuration file
-  # --
-  # -- ---------------------------------
-  # -- [Dependencies and Assumptions]
-  # -- ---------------------------------
-  # --
-  # --   1. json file is formatted with below keys (and value types)
-  # --
-  # --      - replace_file_path   : value type => String
-  # --      - line_search_strings : value type => Array of Strings
-  # --      - replace_with_string : value type => String
-  # --
-  # --   2. every file specified exists and is readable + writeable
-  # --
-  def overwrite_lines
-
-    return unless File.exists? @c[:overwrite][:spec_filepath]
-
-    pointers = JSON.parse(
-                  File.read(@c[:overwrite][:spec_filepath]),
-                  object_class: OpenStruct
-    )
-
-    pointers.each do | pinpoint |
-
-      Files.find_replace_lines(
-        pinpoint.replace_file_path,
-        pinpoint.line_search_strings,
-        pinpoint.replace_with_string
-      )
-
-    end
-
-  end
-
-
-end