safedb 0.3.1011 → 0.4.1002

data/lib/modules/mappers/dictionary.rb

@@ -1,288 +0,0 @@
-#!/usr/bin/ruby
-# coding: utf-8
-
-module SafeDb
-
-  require 'inifile'
-
-  # An OpenSession dictionary is a <b>2D (two dimensional) hash</b> data
-  # structure backed by an encrypted file.
-  #
-  # It supports operations to <b>read from</b> and <b>write to</b> a known
-  # filepath and given the correct symmetric encryption key it will
-  #
-  # - decrypt <b>after reading from</b> the file and
-  # - encrypt <b>before writing to</b> the file
-  #
-  # This dictionary extends {Hash} in order to deliver on its core key value
-  # storage and retrieve use cases. Extend this dictionary and provide
-  # context specific methods through constants to read and write context
-  # specific data.
-  #
-  # == The <em>Current</em> Dictionary Section
-  #
-  # This Dictionary is <b>two-dimensional</b> so all key-value pairs are stored
-  # under the auspices of a section.
-  #
-  # The Dictionary can track the <b>current section</b> for you and all data
-  # exchanges can occur in lieu of a single section if you so wish by using
-  # the provided {put} and {get} methods.
-  #
-  # To employ section management functionality you should pass in a current
-  # <b>section id</b> when creating the dictionary.
-  #
-  # @example
-  #    To use the dictionary in the raw (unextended) format you create
-  #    write and read it like this.
-  #
-  #    ----------------------------------------------------------------------
-  #
-  #    my_dictionary = Dictionary.create( "/path/to/backing/file" )
-  #
-  #    my_dictionary["user23"] = {}
-  #    my_dictionary["user23"]["Name"] = "Joe Bloggs"
-  #    my_dictionary["user23"]["Email"] = "joebloggs@example.com"
-  #    my_dictionary["user23"]["Phone"] = "+44 07342 800080"
-  #
-  #    my_dictionary.write( "crypt-key-1234-wxyz" )
-  #
-  #    ----------------------------------------------------------------------
-  #
-  #    my_dictionary = Dictionary.create( "/path/to/backing/file", "crypt-key-1234-wxyz" )
-  #    puts my_dictionary.has_key? "user23"   # => true
-  #    puts my_dictionary["user23"].length    # => 3
-  #    puts my_dictionary["user23"]["Email"]  # => "joebloggs@example.com"
-  #
-  #    ----------------------------------------------------------------------
-  class Dictionary < Hash
-
-    attr_accessor :backing_filepath, :section_id
-
-
-    # Create either a new empty dictionary or unmarshal (deserialize) the
-    # dictionary from an encrypted file depending on whether a file exists
-    # at the backing_file parameter location.
-    #
-    # If the backing file indeed exists, the crypt key will be employed to
-    # decode and then decrypt the contents before the unmarshal operation.
-    #
-    # The filepath is stored as an instance variable hence the {write}
-    # operation does not need to be told <b>where to?</b>
-    #
-    # @example
-    #    # Create Dictionary the first time
-    #    my_dictionary = Dictionary.create( "/path/to/backing/file" )
-    #
-    #    # Create Dictionary from an Encrypted Backing File
-    #    my_dictionary = Dictionary.create( "/path/to/backing/file", "crypt-key-1234-wxyz" )
-    #
-    # @param backing_file [String]
-    #    the backing file is the filepath to this Dictionary's encrypted
-    #    backing file when serialized. If no file exists at this path the
-    #    operation will instantiate and return a new empty {Hash} object.
-    #
-    # @param crypt_key [String]
-    #    if the backing file exists then this parameter must contain a
-    #    robust symmetric decryption key. The symmetric key will be used
-    #    for decryption after the base64 encoded file is read.
-    #
-    #    Note that the decryption key is never part of the dictionary object.
-    #    This class method knows it but the new Dictionary has no crypt key
-    #    instance variable. Another crypt key must then be introduced when
-    #    serializing (writing) the dictionary back into a file.
-    #
-    # @return [Dictionary]
-    #    return a new Dictionary that knows where to go if it needs
-    #    to read (deserialize) or write (serialize) itself.
-    #
-    #    If no file exists at the path a new empty {Hash} object is
-    #    returned.
-    #
-    #    If a file exists, then the crypt_key parameter is expected
-    #    to be the decryption and key and the dictionary will be based
-    #    on the decrypted contents of the file.
-    #
-    # @raise [ArgumentError]
-    #    An {ArgumentError} is raised if either no decryption key is provided
-    #    or one that is unsuitable (ie was not used within the encryption).
-    #    Errors can also arise if the block coding and decoding has not been
-    #    done satisfactorily.
-    def self.create backing_file, crypt_key = nil
-
-      key_missing = File.file?( backing_file ) && crypt_key.nil?
-      raise ArgumentError, "No crypt key provided for file #{backing_file}" if key_missing
-
-      dictionary = Dictionary.new
-      dictionary.backing_filepath = backing_file
-
-      return dictionary unless File.file? backing_file
-
-      file_contents = File.read( backing_file ).strip
-      plaintext_str = file_contents.block_decode_decrypt( crypt_key )
-      dictionary.ingest_contents( plaintext_str )
-
-      return dictionary
-      
-    end
-
-
-    # Create either a new dictionary containing the specified section or unmarshal
-    # (deserialize) the dictionary from an encrypted file depending on whether a
-    # file exists at the backing_file parameter location and then <b>create</b> the
-    # section <b>only if it does not exist</b>.
-    #
-    # If the backing file indeed exists, the crypt key will be employed to
-    # decode and then decrypt the contents before the unmarshal operation.
-    #
-    # The filepath is stored as an instance variable hence the {write}
-    # operation does not need to be told <b>where to?</b>
-    #
-    # This dictionary will also know which <b>"section"</b> should be used to
-    # put, add, update and delete key/value data. You can employ this dictionary
-    # such that <b>each instance only creates, updates, removes and/or reads</b>
-    # from a single section.
-    #
-    # @example
-    #    # Create Dictionary the first time with a section.
-    #    my_dictionary = Dictionary.create( "/path/to/file", "Europe" )
-    #
-    #    # Create Dictionary from an Encrypted Backing File
-    #    my_dictionary = Dictionary.create( "/path/to/file", "Europe", "1234-wxyz" )
-    #
-    # @param backing_file [String]
-    #    the backing file is the filepath to this Dictionary's encrypted
-    #    backing file when serialized.
-    #
-    # @param section_id [String]
-    #    the created dictionary know which <b>section</b> should be used to
-    #    put, add, update and delete key/value data. If the backing file
-    #    does not exist a new section is created in the empty dictionary.
-    #
-    #    If the file exists a new section is created only if it is not
-    #    already present inside the dictionary.
-    #
-    # @param crypt_key [String]
-    #    if the backing file exists then this parameter must contain a
-    #    robust symmetric decryption key. The symmetric key will be used
-    #    for decryption after the base64 encoded file is read.
-    #
-    #    Note that the decryption key is never part of the dictionary object.
-    #    This class method knows it but the new Dictionary has no crypt key
-    #    instance variable. Another crypt key must then be introduced when
-    #    serializing (writing) the dictionary back into a file.
-    #
-    # @return [Dictionary]
-    #    return a new Dictionary that knows where to go if it needs
-    #    to read (deserialize) or write (serialize) itself.
-    #
-    #    If no file exists at the path a new empty {Hash} object is
-    #    returned.
-    #
-    #    If a file exists, then the crypt_key parameter is expected
-    #    to be the decryption and key and the dictionary will be based
-    #    on the decrypted contents of the file.
-    #
-    # @raise [ArgumentError]
-    #    An {ArgumentError} is raised if either no decryption key is provided
-    #    or one that is unsuitable (ie was not used within the encryption).
-    #    Errors can also arise if the block coding and decoding has not been
-    #    done satisfactorily.
-    def self.create_with_section backing_file, section_id, crypt_key = nil
-
-      dictionary = create( backing_file, crypt_key = nil )
-      dictionary.section_id = section_id
-      dictionary[section_id] = {} unless dictionary.has_key?( section_id )
-
-      return dictionary
-      
-    end
-
-
-    # Write the data in this dictionary hash map into a file-system
-    # backend mirror whose path was specified in the {Dictionary.create}
-    # factory method.
-    #
-    # Technology for encryption at rest is mandatory when using this
-    # Dictionary to write and read files from the filesystem.
-    #
-    # Calling this {self.write} method when the file at the prescribed path
-    # does not exist results in the directory structure being created
-    # (if necessary) and then the (possibly encrypted) file being written.
-    #
-    # @param crypt_key [String]
-    #    this parameter must contain a robust symmetric crypt key to use for
-    #    the encryption before writing to the filesystem.
-    #
-    #    Note that the decryption key is never part of the dictionary object.
-    #    For uncrackable security this key must be changed every time the
-    #    file is written.
-    def write crypt_key
-
-      ini_file = IniFile.new
-      self.each_key do |section_name|
-        ini_file[section_name] = self[section_name]
-      end
-
-      crypted_text = ini_file.to_s.encrypt_block_encode( crypt_key )
-
-      FileUtils.mkdir_p File.dirname(@backing_filepath)
-      File.write @backing_filepath, crypted_text
-
-    end
-
-
-
-    def get key_name
-      return self[@section_id][key_name]
-    end
-
-
-
-    def put key_name, key_value
-      self[@section_id][key_name] = key_value
-    end
-
-
-
-
-    # Ingest the contents of the INI string and merge it into a
-    # this object which is a {Hash}.
-    #
-    # @param the_contents [String]
-    #    the INI string that will be ingested and morphed into
-    #    this dictionary.
-    #
-    # @raise [ArgumentError]
-    #    if the content contains any nil section name, key name
-    #    or key value.
-    def ingest_contents the_contents
-      
-      ini_file = IniFile.new( :content => the_contents )
-      ini_file.each do | data_group, data_key, data_value |
-        ingest_entry data_group, data_key, data_value
-      end
-
-    end
-
-
-    private
-
-
-    def ingest_entry section_name, key_name, value
-
-      msg = "A NIL object detected during ingestion of file [#{@filepath}]."
-      raise ArgumentError.new msg if section_name.nil? || key_name.nil? || value.nil?
-
-      if self.has_key? section_name then
-        self[section_name][key_name] = value
-      else
-        self.store section_name, { key_name => value }
-      end
-
-    end
-
-
-  end
-
-
-end

data/lib/session/time.stamp.rb

@@ -1,340 +0,0 @@
-#!/usr/bin/ruby
-
-module OpenSession
-
-  require 'singleton'
-
-  # This stamp sits at the centre of a fundamental DevOps pattern concerned
-  # with infrastructure provisioning and configuraion management.
-  #
-  # The central idea behind the pattern is to link every infrastructure
-  # object created during a session with a reference accurate to the nearest
-  # centi-second denoting the moment the software runtime (session) began.
-  class Stamp
-    include Singleton
-
-    attr_reader :time_now
-
-    # Return two digit [mo] month index from 01 to 12.
-    # @example 02 => in February
-    def self.mo
-      return Stamp.instance.time_now.strftime "%m"
-    end
-
-
-    # Return three character abbreviated month name.
-    # @example feb => in February
-    def self.mmm
-      return Stamp.instance.time_now.strftime( "%b" ).downcase
-    end
-
-
-    # Return three character abbreviated day of week.
-    # @example tue => on Tuesday
-    def self.ddd
-      return Stamp.instance.time_now.strftime( "%a" ).downcase
-    end
-
-
-    # Return two digit (character) hour of day from 00 to 23.
-    # @example 22 => between 22.00.00 and 22.59.59 inclusive
-    def self.hh
-      return Stamp.instance.time_now.strftime "%H"
-    end
-
-
-    # Return two digit minute of hour from [00] to [59].
-    def self.mm
-      return Stamp.instance.time_now.strftime "%M"
-    end
-
-
-    # Return two digit second of minute from [00] to [59].
-    def self.ss
-      return Stamp.instance.time_now.strftime "%S"
-    end
-
-
-    # Return a [3 digit] second and tenth of second
-    # representation.
-    #
-    # The final digit is derived from the 1000 sliced
-    # millisecond of second running from 000 to 999.
-    #
-    # <tt>Truncation (Not Rounding)</tt>
-    #
-    # The [final] digit is acquired by TRUNCATING
-    # (chopping off) the last 2 of the 3 millisecond
-    # digits. No rounding is applied.
-    #
-    # The 3 returned digits comprise of the
-    #
-    # - second of minute => 2 digits | [00] to [59] (and)
-    # - tenth of second  => 1 digit from [0] to [9]
-    #
-    # @example
-    #
-    #  => The time at the 562nd millisecond  of the 49th
-    #     second of the minute.
-    #
-    #  => 3 chars
-    #  => 495
-    def self.sst
-      millisec_string = Stamp.instance.time_now.strftime "%L"
-      return "#{ss}#{millisec_string[0]}"
-    end
-
-
-    # Return the [two] digit year (eg 19 for 2019).
-    # that we are currently in.
-    def self.yy
-      return Stamp.instance.time_now.strftime("%Y")[2..-1]
-    end
-
-
-    # Return the [four] digit year (eg 2019)
-    # that we are currently in.
-    def self.yyyy
-      return Stamp.instance.time_now.strftime("%Y")
-    end
-
-
-    # Return 3 digit julian day of year [001] to [366].
-    def self.jjj
-      return Stamp.instance.time_now.strftime "%j"
-    end
-
-
-    # [yymo_mmm] returns an amalgam of
-    #
-    #    => the two-digit year
-    #    => the two-digit month index (starting at 01)
-    #    => a period (separator)
-    #    => the abbreviated month name
-    #
-    # @example
-    #   => 1908.aug
-    #   => for August 2019
-    #
-    def self.yymo_mmm
-      return "#{yy}#{mo}.#{mmm}"
-    end
-
-
-    # Given two integer parameters (month index and 4 digit year) representing
-    # the month in question this method returns the [PREVIOUS MONTHS] character
-    # amalgam in the format [yymo_mmm] where
-    #
-    #    => yy  | previous month's two-digit year
-    #    => mo  | previous month's two-digit month index
-    #    => .   | a period (separator)
-    #    => mmm | previous month's abbreviated month name
-    #
-    # -------------------
-    # Example 1 (Simple)
-    # -------------------
-    #
-    #  returns char => 1907.jul
-    #  4 parameters => 8, 2019
-    #  representing => August, 2019
-    #
-    # ----------------------
-    # Example 2 (Last Year)
-    # ----------------------
-    #
-    #  returns char => 1812.dec
-    #  4 parameters => 1, 2019
-    #  representing => January, 2019
-    def self.previous_month_chars this_month_index, this_4digit_year
-
-      prev_month_index = this_month_index == 1 ? 12 : ( this_month_index - 1 )
-      prev_2dig_mn_pad = sprintf '%02d', prev_month_index
-      prev_4digit_year = this_month_index == 1 ? ( this_4digit_year - 1 ) : this_4digit_year
-      prev_twodigit_yr = "#{prev_4digit_year.to_s}"[2..-1]
-      prev_months_name = Date::ABBR_MONTHNAMES[prev_month_index].downcase
-
-      return "#{prev_twodigit_yr}#{prev_2dig_mn_pad}.#{prev_months_name}"
-
-    end
-
-    # Using the current class time this method returns
-    # the character amalgam for the [PREVIOUS MONTH] in
-    # the format [yymo_mmm] where
-    #
-    #    => yy  | last month's two-digit year
-    #    => mo  | last month's two-digit month index
-    #    => .   | a period (separator)
-    #    => mmm | last month's abbreviated month name
-    #
-    # -------------------
-    # Example 1 (Simple)
-    # -------------------
-    #
-    #  returns => 1907.jul
-    #  if this month is => August 2019
-    #
-    # ----------------------
-    # Example 2 (Last Year)
-    # ----------------------
-    #
-    #  returns => 1812.dec
-    #  if this month is => January 2019
-    def self.yymo_mmm_prev
-      return previous_month_chars mo.to_i, yyyy.to_i
-    end
-
-
-    # Return 5 digit amalgam of year and julian day.
-    #  eg [19003] for [January 3rd 2019]
-    def self.yyjjj
-      return "#{yy}#{jjj}"
-    end
-
-
-    # Return the 4 digit amalgam of the hour and minute
-    # using the 24 hour clock.
-    #
-    # @example
-    #   => 1525
-    #   => 03:25 pm
-    def self.hhmm
-      return "#{hh}#{mm}"
-    end
-
-
-    # Return the time of day to a TENTH of a second accuracy.
-    # [8] characters will always be returned with the 5th one
-    # being the (period) separator.
-    #
-    # The first (separated) segment delivers a hhmm 24 hour
-    # clock representation of the stamped time.
-    #
-    # The 3 digits of the second segment comprise of
-    #
-    #   second of minute => 2 digits | [00] to [59]
-    #   tenth of second  => 1 digit from [0] to [9]
-    #
-    # @example
-    #   => The time at the 562nd millisecond  of the 49th
-    #      second of the 23rd minute of the 17th hour of
-    #      the day ( 17:23:49.562 )
-    #
-    #   => 8 chars
-    #   => 1723.495
-    def self.hhmm_sst
-      return "#{hhmm}.#{sst}"
-    end
-
-
-    # Return a string timestampt that is a period separated
-    # amalgam of the 2 digit year, 3 digit julian day, 2 digit
-    # hour, 2 digit minute, 2 digit second and 1 digit rounded
-    # down tenth of second.
-    #
-    # @example
-    #   => 19003.1025
-    #   => 10:25 am on January 3rd 2019
-    #
-    #
-    # Return the time of day to a TENTH of a second accuracy.
-    # [8] characters will always be returned with the 5th one
-    # being the (period) separator.
-    #
-    # The first (separated) segment delivers a hhmm 24 hour
-    # clock representation of the stamped time.
-    #
-    # The 3 digits of the second segment comprise of
-    #
-    # - second of minute => 2 digits | [00] to [59]
-    # - tenth of second  => 1 digit from [0] to [9]
-    #
-    # @example
-    #   => The time at the 562nd millisecond  of the 49th
-    #      second of the 23rd minute of the 17th hour of
-    #      the day ( 17:23:49.562 )
-    #
-    #   => 8 chars
-    #   => 1723.495
-    def self.yyjjj_hhmm_sst
-      return "#{yyjjj}.#{hhmm}.#{sst}"
-    end
-
-
-    # Return a string timestampt that is a period separated
-    # amalgam of the 2 digit year, 3 digit julian day, 2 digit
-    # hour, 2 digit minute, 2 digit second and <b>9 digit</b>
-    # nanosecond.
-    #
-    # @example
-    #   return  => 19003.1725.42.836592034
-    #   4 time  => 17:25:42 am on January 3rd 2019
-    #
-    # As per the above example, the time returned
-    #
-    # - is the 836592034 <b>nanosecond</b>
-    # - of the 42nd <b>second</b>
-    # - of the 25th <b>minute</b>
-    # - of the 17th <b>hour</b>
-    # - of the 3rd <b>day</b>
-    # - of the 20th <b>year</b>
-    # - of the 21st <b>century</b>
-    #
-    # @return [String]
-    #    Return the time of day to nanosecond accuracy.
-    #    23 characters are always returned with three (3) period
-    #    separators at the 6th, 11th and 14th positions.
-    def self.yyjjj_hhmm_ss_nanosec
-      nanosec_str = Stamp.instance.time_now.strftime "%9N"
-      return "#{yyjjj}.#{hhmm}.#{ss}.#{nanosec_str}"
-    end
-
-
-    # Return the Rubyfied time zone being used.
-    def self.zone
-      return Stamp.instance.time_now.zone
-    end
-
-
-    # Log segments of time pertaining to the time stamp.
-    # @todo
-    #    move method contents into test class
-    def self.log_instance_time
-
-      log.info(x) { "[stamp] -------------- => -------------------------------- #" }
-      log.info(x) { "[stamp] eco time stamp => [#{Stamp.instance.time_now.ctime}]" }
-      log.info(x) { "[stamp] -------------- => -------------------------------- #" }
-      log.info(x) { "[stamp] Univ Time Zone => #{zone}"  }
-      log.info(x) { "[stamp] Month Index is => #{mo}"    }
-      log.info(x) { "[stamp] Month Name is  => #{mmm}"   }
-      log.info(x) { "[stamp] Day Of Week is => #{ddd}"   }
-      log.info(x) { "[stamp] -------------- => -------------------------------- #" }
-      log.info(x) { "[stamp] Two Digit Year => #{yy}"    }
-      log.info(x) { "[stamp] Julian Cal Day => #{jjj}"   }
-      log.info(x) { "[stamp] Yr and Jul Day => #{yyjjj}" }
-      log.info(x) { "[stamp] Hour of Theday => #{hh}"    }
-      log.info(x) { "[stamp] Minute of Hour => #{mm}"    }
-      log.info(x) { "[stamp] Hour + Minute  => #{hhmm}"  }
-      log.info(x) { "[stamp] Second of Min  => #{ss}"    }
-      log.info(x) { "[stamp] 600 Min Slices => #{sst}"   }
-      log.info(x) { "[stamp] -------------- => -------------------------------- #" }
-      log.info(x) { "[stamp] The Time Stamp => #{yyjjj_hhmm_sst}" }
-      log.info(x) { "[stamp] -------------- => -------------------------------- #" }
-
-    end
-
-
-    # This singleton (one instance) class sets the time just once.
-    def initialize
-
-      @time_now = Time.now;
-
-    end
-
-
-############    Stamp.log_instance_time
-
-
-  end
-
-
-end