safedb 0.3.1011 → 0.4.1002

data/lib/{keytools → utils}/key.error.rb

@@ -3,10 +3,10 @@
 module SafeDb
 
 
-  # This class is the parent to all opensession errors
+  # This class is the parent to all openbranch errors
   # that originate from the command line.
   #
-  # All opensession cli originating errors are about
+  # All openbranch cli originating errors are about
   #
   # - a problem with the input or
   # - a problem with the current state or

data/lib/{keytools → utils}/key.pass.rb

@@ -43,14 +43,14 @@ module SafeDb
         assert_min_size MINIMUM_PASSWORD_SIZE
 
         sleep(1)
-        puts "Password:"
+        puts "Enter Password:"
         first_secret = STDIN.noecho(&:gets).chomp
 
         assert_input_text_size first_secret.length, MINIMUM_PASSWORD_SIZE
         return first_secret unless prompt_twice
 
         sleep(1)
-        puts "Re-enter the password:"
+        puts "Re-enter Password:"
         check_secret = STDIN.noecho(&:gets).chomp
 
         assert_same_size_text first_secret, check_secret

data/lib/{keytools → utils/keys}/key.rb

@@ -143,12 +143,16 @@ module SafeDb
 
 
     def self.to_random_bits the_byte_length
+
+      require 'securerandom'
+
       random_bit_string = ""
       for n in 1 .. the_byte_length
         random_integer = SecureRandom.random_number( EIGHT_BIT_INTEGER_SIZE )
         random_bit_string += "%08d" % [ random_integer.to_s(2) ]
       end
       return random_bit_string
+
     end
 
 
@@ -271,7 +275,7 @@ module SafeDb
     #    If the bit value string for this key is nil.
     #    Or if the bit string length is not a multiple of six.
     #    Or if it contains any character that is not a 1 or 0.
-    def to_char64
+    def to_char64()
       assert_non_nil_bits
       return Key64.from_bits( @bit_string )
     end
@@ -288,7 +292,7 @@ module SafeDb
     # @return [Byte]
     #    a non-printable binary string of eight (8) bit bytes which can be
     #    used as input to both digest and symmetric cipher functions.
-    def to_binary
+    def to_binary()
       return [ to_s ].pack("B*")
     end
 

data/lib/{logging/gem.logging.rb → utils/logs/logger.rb}

@@ -1,5 +1,5 @@
 require "logger"
-require "session/user.home"
+
 
 # [MIXIN] magic is deployed to hand out DevOps quality logging
 # features to any class that includes the logging module.
@@ -22,12 +22,12 @@ require "session/user.home"
 # Refer to the below link for excellent coverage of mixins.
 # @see http://ruby-doc.com/docs/ProgrammingRuby/html/tut_modules.html
 #
-module OpenLogger
+module LogImpl
 
   @@gem_name = "safedb.net"
-  @@gem_base = File.join OpenSession::Home.dir, ".#{@@gem_name}"
-  FileUtils.mkdir_p @@gem_base unless File.exists? @@gem_base
-  @@log_path = File.join @@gem_base, "safedb.net-cli.log"
+  @@gem_base = File.join( Dir.home(), ".#{@@gem_name}" )
+  FileUtils.mkdir_p( @@gem_base ) unless File.exists?( @@gem_base )
+  @@log_path = File.join( @@gem_base, "safedb-summary.log" )
 
 
   # Classes that include (MIXIN) this logging module will
@@ -88,6 +88,7 @@ module OpenLogger
   def get_logger
 
     file_logger = Logger.new @@log_path
+    file_logger.level = Logger::INFO
     original_formatter = Logger::Formatter.new
 
     file_logger.formatter = proc { |severity, datetime, progname, msg|

data/lib/{keytools/key.pair.rb → utils/store/datamap.rb}

@@ -5,7 +5,7 @@ module SafeDb
 
   require 'inifile'
 
-  # KeyPair is a <b>key-value</b> store backed by a plain-text file in
+  # DataMap is a <b>key-value</b> store backed by a plain-text file in
   # an <b>INI format</b> that sits on an accessible file-system.
   #
   #
@@ -13,11 +13,11 @@ module SafeDb
   #
   # Issue the below ruby calls and specify a /path/to/file
   #
-  #    keymap = KeyPair.new "/path/to/file"
+  #    datamap = DataMap.new ( "/path/to/file" )
   #
-  #    keymap.use "phone_numbers"
-  #    keymap.set "joe", "0044 7500 123456"
-  #    keymap.set "amy", "0044 7678 123456"
+  #    datamap.use ( "phone_numbers"           )
+  #    datamap.set ( "joe", "0044 7500 123456" )
+  #    datamap.set ( "amy", "0044 7678 123456" )
   #
   # Now visit the file to see your exchanged data.
   #
@@ -35,7 +35,7 @@ module SafeDb
   # You do not need a new object to switch sections - just go ahead and
   # use another another one.
   #
-  # Remember that KeyPair is <b>two-dimensional</b> data structure so all
+  # Remember that DataMap is <b>two-dimensional</b> data structure so all
   # key-value pairs are stored under the auspices of a section.
   #
   # == Key-Value Pair Exchanges
@@ -47,7 +47,7 @@ module SafeDb
   #
   # The name given to the default group can be specified to the constructor.
   # If none is provided the aptly named "default" is used.
-  class KeyPair
+  class DataMap
 
     # Initialize the key value store and auto write a time stamp that
     # has nano-second accuracy with a key whose name is gleened from
@@ -64,9 +64,9 @@ module SafeDb
     # @param the_default_group [String]
     #    the name of the default group. If none is presented this value
     #    will default to the aptly named "default".
-    def initialize backing_file_path
+    def initialize( backing_file_path )
       @file_path = backing_file_path
-      create_dir_if_necessary
+      create_dir_unless_exists()
     end
 
 
@@ -76,7 +76,7 @@ module SafeDb
     # @param the_section_name [String]
     #    the non-nil and non whitespace only section name that will lead a
     #    set of key-value pairs in the INI formatted file.
-    def use the_section_name
+    def use( the_section_name )
       raise ArgumentError, "Cannot use a Nil section name." if the_section_name.nil?
       @section_to_use = the_section_name
     end
@@ -86,7 +86,7 @@ module SafeDb
     #
     # @param key_name [String] the name of the key whose value is to be written
     # @param key_value [String] the data item value of the key specified
-    def set key_name, key_value
+    def set( key_name, key_value )
       raise ArgumentError, "Cannot set a Nil section name." if @section_to_use.nil?
       write @section_to_use, key_name, key_value
     end
@@ -98,14 +98,25 @@ module SafeDb
     # @param key_name [String] the name of the key whose value is to be written
     # @return [String]
     #    return the value of the configuration directive in the default group
-    def get key_name
+    def get( key_name )
       raise ArgumentError, "Cannot get from a Nil section name." if @section_to_use.nil?
-      read @section_to_use, key_name
+      read( @section_to_use, key_name )
+    end
+
+
+    # Return the name of the currently in-focus section that has been set using
+    # the {use} method.
+    #
+    # @return [String]
+    #    return the name of the currently in-focus section
+    def section()
+      raise ArgumentError, "The use method has not specified a section." if @section_to_use.nil?
+      return @section_to_use
     end
 
 
     # Write the key/value pair in the parameter into this key/value store's
-    # base file-system backing INI file.
+    # backing INI file.
     #
     # This method assumes the existence of the backing configuration file at
     # the @file_path instance variable that was set during initialization.
@@ -120,12 +131,12 @@ module SafeDb
     # @param key [String] the key name of config directive to be written into the file
     # @param value [String] value of the config directive to be written into the file
     #
-    def write section_name, key, value
+    def write( section_name, key, value )
 
-      config_map = IniFile.new( :filename => @file_path, :encoding => 'UTF-8' )
-      config_map = IniFile.load( @file_path ) if File.file? @file_path
-      config_map[section_name][key] = value
-      config_map.write
+      data_map = IniFile.new( :filename => @file_path, :encoding => 'UTF-8' )
+      data_map = IniFile.load( @file_path ) if File.file? @file_path
+      data_map[section_name][key] = value
+      data_map.write
 
     end
 
@@ -142,7 +153,7 @@ module SafeDb
     #     cause the key value to not be retrieved. This can range from
     #     non-existent directories and files, non readable files, incorrect
     #     configurations right down to missing keys or even missing values.
-    def read section_name, key_name
+    def read( section_name, key_name )
 
       raise ArgumentError.new "No section given." if section_name.nil? || section_name.strip.empty?
       raise ArgumentError.new "No parameter key given." if key_name.nil? || key_name.strip.empty?
@@ -184,7 +195,7 @@ module SafeDb
     # raise [ArgumentError]
     #    if the configuration file does not exist or is empty
     #    if the paramter key_name is nil, empty or contains only whitespace
-    def contains? key_name
+    def contains?( key_name )
 
       raise ArgumentError.new "No parameter key given." if key_name.nil? || key_name.strip.empty?
       raise ArgumentError.new "No file found at [ #{@file_path} ]" unless File.exists? @file_path
@@ -198,7 +209,6 @@ module SafeDb
     end
 
 
-
     # Return true if the settings configuration file contains the specified
     # section name. This method ignores whatever section that may or may not
     # have been pointed to by the use command.
@@ -208,7 +218,7 @@ module SafeDb
     #
     # @return [Boolean]
     #    return true if a section exists with the specified name
-    def has_section? section_name
+    def has_section?( section_name )
 
       KeyError.not_new( section_name, self )
 
@@ -222,7 +232,6 @@ module SafeDb
     end
 
 
-
     # Get the time stamp that was written to the key-value store at
     # the point it was first initialized and then subsequently written
     # out (serialized) onto the file-system.
@@ -234,21 +243,30 @@ module SafeDb
     #    the string time stamp denoting the first time this key-value
     #    store was first initialized and then subsequently written out
     #    (serialized) onto the file-system.
-    def time_stamp
+    def time_stamp()
       return get INIT_TIME_STAMP_NAME
     end
 
 
+    # Fetch this one-dimensional data store as a string in INI file format.
+    # @return [String] an INI formatted string representation of this data
+    def as_string()
+
+      data_map = IniFile.new( :filename => @file_path, :encoding => 'UTF-8' )
+      data_map = IniFile.load( @file_path ) if File.file? @file_path
+      return data_map.to_s
+
+    end
 
-    private
 
+    private
 
 
-    def create_dir_if_necessary
+    def create_dir_unless_exists()
 
-      config_directory = File.dirname @file_path
-      return if (File.exist? config_directory) && (File.directory? config_directory)
-      FileUtils.mkdir_p config_directory
+      file_dir = File.dirname( @file_path )
+      return if (File.exist? file_dir) && (File.directory? file_dir)
+      FileUtils.mkdir_p( file_dir )
 
     end
 

data/lib/{keytools/key.db.rb → utils/store/datastore.rb}

@@ -9,6 +9,16 @@ module SafeDb
   # (put, add etc) <b>after reading and then decrypting it</b> from a
   # file and <b>before encrypting and then writing it</b> to a file.
   #
+  # == Difference Between DataStore and DataStore
+  #
+  # The DataStore is a JSON backed store that streams to and from INI formatted
+  # data.
+  # The DataStore  is preferred for human readable data which is
+  # precisely 2 dimensional. The streamed DataMap is JSON which
+  # at scale isn't human readable but the data structure is
+  # N dimensional and it supports nested structures such as
+  # lists, maps, numbers and booleans.
+  #
   # It provides behaviour to which we can create, append (add), update
   # (change), read parts and delete essentially two structures
   #
@@ -37,7 +47,7 @@ module SafeDb
   # - other hashes
   # - booleans
   # - integers and floats
-  class KeyDb < Hash
+  class DataStore < Hash
 
     # Return a key database data structure that is instantiated from
     # the parameter JSON string.
@@ -46,18 +56,43 @@ module SafeDb
     #    this json formatted data structure will be converted into a
     #    a Ruby hash (map) data structure and returned.
     #
-    # @return [KeyDb]
+    # @return [DataStore]
     #    a hash data structure that has been instantiated as per the
     #    parameter json string content.
     def self.from_json( db_json_string )
 
-      data_db = KeyDb.new()
+      data_db = DataStore.new()
       data_db.merge!( JSON.parse( db_json_string ) )
       return data_db
 
     end
 
 
+    # Set the section to use for future data exchanges via the ubiquitous {get}
+    # and {set} methods as well as the query {contains} key method.
+    #
+    # @param section [String]
+    #    the non-nil and non whitespace only section name that will lead a
+    #    set of key-value pairs in the INI formatted file.
+    def use section
+      raise ArgumentError, "Cannot use a Nil section." if section.nil?
+      @section = section
+    end
+
+
+    # Stash the setting directive and its value into the configuration file
+    # using the default settings group.
+    #
+    # @param key_name [String] the name of the key whose value is to be written
+    # @param key_value [String] the data item value of the key specified
+    def set key_name, key_value
+      raise ArgumentError, "Cannot set a Nil (section)" if @section.nil?
+      raise ArgumentError, "Cannot set a Nil key name." if key_name.nil?
+      raise ArgumentError, "Cannot set a Nil key value" if key_value.nil?
+      create_entry( @section, key_name, key_value )
+    end
+
+
 
     # Create a new key value entry inside a dictionary with the specified
     # name at the root of this database. Successful completion means the
@@ -223,107 +258,6 @@ module SafeDb
     end
 
 
-    # Read and inject into this envelope, the data structure found in a
-    # file at the path specified in the first parameter.
-    #
-    # Symmetric cryptography is mandatory for the envelope so we must
-    # <b>encrypt before writing</b> and <b>decrypt after reading</b>.
-    #
-    # An argument error will result if a suitable key is not provided.
-    #
-    # If the file does not exist (denoting the first read) all this method
-    # does is to stash the filepath as an instance variable and igore the
-    # decryption key which can be nil (or ommitted).
-    #
-    # @param the_filepath [String]
-    #     absolute path to the file which acts as the persistent mirror to
-    #     this data structure envelope.
-    #
-    # @param decryption_key [String]
-    #     encryption at rest is a given so this mandatory parameter must
-    #     contain a robust symmetric decryption key. The key will be used
-    #     for decryption after the read and it will not linger (ie not cached
-    #     as an instance variable).
-    #
-    # @raise [ArgumentError] if the decryption key is not robust enough.
-    def read the_filepath, decryption_key = nil
-
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-
-      raise RuntimeError, "This KeyDb.read() software is never called so how can I be here?"
-
-      @filepath = the_filepath
-      return unless File.exists? @filepath
-
-      cipher_text = Base64.decode64( File.read( @filepath ).strip )
-      plain_text = ToolBelt::Blowfish.decryptor( cipher_text, decryption_key )
-
-      data_structure = JSON.parse plain_text
-      self.merge! data_structure
-
-    end
-
-
-    # Write the data in this envelope hash map into a file-system
-    # backed mirror whose path was specified in the {self.read} method.
-    #
-    # Technology for encryption at rest is supported by this dictionary
-    # and to this aim, please endeavour to post a robust symmetric
-    # encryption key.
-    #
-    # 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 encrypted file being written.
-    #
-    # @param encryption_key [String]
-    #     encryption at rest is a given so this mandatory parameter must
-    #     contain a robust symmetric encryption key. The symmetric key will
-    #     be used for the decryption after the read. Note that the decryption
-    #     key does not linger meaning it isn't cached in an instance variable.
-    def write encryption_key
-
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-      # @todo -> this is confused - it uses INI but above methods use JSON
-
-      raise RuntimeError, "This KeyDb.write( key ) software is never called so how can I be here?"
-
-      FileUtils.mkdir_p(File.dirname(@filepath))
-      cipher_text = Base64.encode64 ToolBelt::Blowfish.encryptor( self.to_json, encryption_key )
-      File.write @filepath, cipher_text
-
-      puts ""
-      puts "=== ============================"
-      puts "=== Envelope State ============="
-      puts "=== ============================"
-
-      a_ini_file = IniFile.new
-      self.each_key do |section_name|
-        a_ini_file[section_name] = self[section_name]
-      end
-      puts a_ini_file.to_s
-
-      puts "=== ============================"
-      puts ""
-
-    end
-
-
   end