configliere 0.0.1

data/lib/configliere/crypter.rb

@@ -0,0 +1,72 @@
+require 'openssl'
+require 'digest/sha2'
+module Configliere
+  #
+  # Encrypt and decrypt values in configliere stores
+  #
+  module Crypter
+    CIPHER_TYPE = "aes-256-cbc" unless defined?(CIPHER_TYPE)
+
+    #
+    # Encrypt the given string
+    #
+    # @param plaintext the text to encrypt
+    # @param [String] encrypt_pass secret passphrase to encrypt with
+    # @return [String] encrypted text, suitable for deciphering with Crypter#decrypt
+    #
+    def self.encrypt plaintext, encrypt_pass, options={}
+      # The cipher's IV (Initialization Vector) is prepended (unencrypted) to
+      # the ciphertext, which as far as I can tell is safe for our purposes:
+      # http://www.ciphersbyritter.com/NEWS6/CBCIV.HTM
+      cipher     = new_cipher :encrypt, encrypt_pass, options
+      cipher.iv  = iv = cipher.random_iv
+      ciphertext = cipher.update(plaintext)
+      ciphertext << cipher.final
+      combine_iv_and_ciphertext(iv, ciphertext)
+    end
+    #
+    # Decrypt the given string, using the key and iv supplied
+    #
+    # @param ciphertext the text to decrypt, probably produced with Crypter#decrypt
+    # @param [String] encrypt_pass secret passphrase to decrypt with
+    # @return [String] the decrypted plaintext
+    #
+    def self.decrypt iv_and_ciphertext, encrypt_pass, options={}
+      cipher    = new_cipher :decrypt, encrypt_pass, options
+      cipher.iv, ciphertext = separate_iv_and_ciphertext(cipher, iv_and_ciphertext)
+      plaintext = cipher.update(ciphertext)
+      plaintext << cipher.final
+      plaintext
+    end
+  protected
+    #
+    # Create a new cipher machine, with its dials set in the given direction
+    #
+    # @param [:encrypt, :decrypt] direction whether to encrypt or decrypt
+    # @param [String] encrypt_pass secret passphrase to decrypt with
+    #
+    def self.new_cipher direction, encrypt_pass, options={}
+      cipher     = OpenSSL::Cipher::Cipher.new(CIPHER_TYPE)
+      case direction when :encrypt then cipher.encrypt when :decrypt then cipher.decrypt else raise "Bad cipher direction #{direction}" end
+      cipher.key = encrypt_key(encrypt_pass, options)
+      cipher
+    end
+
+    # prepend the initialization vector to the encoded message
+    def self.combine_iv_and_ciphertext iv, message
+      iv + message
+    end
+    # pull the initialization vector from the front of the encoded message
+    def self.separate_iv_and_ciphertext cipher, iv_and_ciphertext
+      idx = cipher.iv_len
+      [ iv_and_ciphertext[0..(idx-1)], iv_and_ciphertext[idx..-1] ]
+    end
+
+    # Convert the encrypt_pass passphrase into the key used for encryption
+    def self.encrypt_key encrypt_pass, options={}
+      raise 'Blank encryption password!' if encrypt_pass.to_s == ''
+      # this provides the required 256 bits of key for the aes-256-cbc cipher
+      Digest::SHA256.digest(encrypt_pass)
+    end
+  end
+end

data/lib/configliere/define.rb

@@ -0,0 +1,151 @@
+module Configliere
+  module Define
+    # Definitions for params: :description, :type, :encrypted, etc.
+    attr_accessor :param_definitions
+
+    # @param param the setting to describe. Either a simple symbol or a dotted param string.
+    # @param definitions the defineables to set (:description, :type, :encrypted, etc.)
+    #
+    # @example
+    #   Settings.define :dest_time, :type => Date, :description => 'Arrival time. If only a date is given, the current time of day on that date is assumed.'
+    #   Settings.define 'delorean.power_source', :description => 'Delorean subsytem supplying power to the Flux Capacitor.'
+    #   Settings.define :password, :required => true, :obscure => true
+    #
+    def define param, definitions={}
+      self.param_definitions[param].merge! definitions
+    end
+
+    def param_definitions
+      # initialize the param_definitions as an auto-vivifying hash if it's never been set
+      @param_definitions ||= Hash.new{|hsh, key| hsh[key] = {} }
+    end
+
+    protected
+    # all params with a value for the definable aspect
+    #
+    # @param definable the aspect to list (:description, :type, :encrypted, etc.)
+    def params_with defineable
+      param_definitions.keys.find_all{|param| param_definitions[param][defineable] } || []
+    end
+
+    def definitions_for defineable
+      hsh = {}
+      param_definitions.each do |param, defs|
+        hsh[param] = defs[defineable] if defs[defineable]
+      end
+      hsh
+    end
+    public
+
+    # performs type coercion
+    def resolve!
+      resolve_types!
+      begin ; super() ; rescue NoMethodError ; nil ; end
+      self
+    end
+
+    def validate!
+      validate_requireds!
+      begin ; super() ; rescue NoMethodError ; nil ; end
+      true
+    end
+
+    # ===========================================================================
+    #
+    # Describe params with
+    #
+    #   Settings.define :param, :description => '...'
+    #
+
+    # gets the description (if any) for the param
+    # @param param the setting to describe. Either a simple symbol or a dotted param string.
+    def description_for param
+      param_definitions[param][:description]
+    end
+
+    # All described params with their descriptions
+    def descriptions
+      definitions_for(:description)
+    end
+
+    # List of params that have descriptions
+    def described_params
+      params_with(:description)
+    end
+
+    # ===========================================================================
+    #
+    # Type coercion
+    #
+    # Define types with
+    #
+    #   Settings.define :param, :type => Date
+    #
+
+    def type_for param
+      param_definitions[param][:type]
+    end
+
+    # All described params with their descriptions
+    def types
+      definitions_for(:type)
+    end
+
+    # List of params that have descriptions
+    def typed_params
+      params_with(:type)
+    end
+
+    # Coerce all params with types defined to their proper form
+    def resolve_types!
+      types.each do |param, type|
+        val = self[param]
+        case
+        when val.nil? then val = nil
+        when (type == :boolean) then
+          if ['false', '0', ''].include?(val.to_s) then val = false else val = true end
+        when (val.to_s == '')   then val = nil
+        when (type == Float)    then val = val.to_f
+        when (type == Integer)  then val = val.to_i
+        when (type == Date)     then val = Date.parse(val)     rescue nil
+        when (type == DateTime) then val = DateTime.parse(val) rescue nil
+        when (type == Time)     then
+          require 'time'
+          val = Time.parse(val) rescue nil
+        when (type == Symbol)   then val = val.to_s.to_sym rescue nil
+        end
+        self[param] = val
+      end
+    end
+
+    # ===========================================================================
+    #
+    # Required params
+    #
+    # Define requireds with
+    #
+    #   Settings.define :param, :required => true
+    #
+
+    # List of params that are required
+    # @return [Array] list of required params
+    def required_params
+      params_with(:required)
+    end
+
+    # Check that all required params are present.
+    def validate_requireds!
+      missing = []
+      required_params.each do |param|
+        missing << param if self[param].nil?
+      end
+      raise "Missing values for #{missing.map{|s| s.to_s }.sort.join(", ")}" if (! missing.empty?)
+    end
+
+  end
+
+  Param.class_eval do
+    include Configliere::Define
+  end
+end
+

data/lib/configliere/encrypted.rb

@@ -0,0 +1,78 @@
+Configliere.use :param_store, :define, :crypter
+
+module Configliere
+  module EncryptedParam
+    # The password used in encrypting params during serialization
+    attr_accessor :encrypt_pass
+
+  protected
+
+    # @example
+    #   Settings.defaults :username=>"mysql_username", :password=>"mysql_password"
+    #   Settings.define :password, :encrypted => true
+    #   Settings.exportable
+    #     #=> {:username => 'mysql_username', :password=>"\345?r`\222\021"\210\312\331\256\356\351\037\367\326" }
+    def export
+      hsh = super()
+      encrypted_params.each do |param|
+        val = hsh.deep_delete(*dotted_to_deep_keys(param)) or next
+        hsh.deep_set( *(dotted_to_encrypted_keys(param) | [encrypted(val)]) )
+      end
+      hsh
+    end
+
+    # decrypts any encrypted params
+    # then calls the next step in the resolve! chain.
+    def resolve!
+      resolve_encrypted!
+      begin ; super() ; rescue NoMethodError ; nil ; end
+      self
+    end
+
+    # import values, decrypting all params marked as encrypted
+    def resolve_encrypted!
+      remove_and_adopt_encrypt_pass_param_if_any!
+      encrypted_params.each do |param|
+        encrypted_val = deep_delete(*dotted_to_encrypted_keys(param)) or next
+        self[param] = self.decrypted(encrypted_val)
+      end
+    end
+
+    # if :encrypted_pass was set as a param, remove it from the hash and set it as an attribute
+    def remove_and_adopt_encrypt_pass_param_if_any!
+      @encrypt_pass = self.delete(:encrypt_pass) if self[:encrypt_pass]
+    end
+
+    # the chain of symbol keys for a dotted path key,
+    # prefixing the last one with "encrypted_"
+    #
+    # @example
+    #    dotted_to_encrypted_keys('amazon.api.key')
+    #    #=> [:amazon, :api, :encrypted_key]
+    def dotted_to_encrypted_keys param
+      encrypted_path = dotted_to_deep_keys(param).dup
+      encrypted_path[-1] = "encrypted_#{encrypted_path.last}".to_sym
+      encrypted_path
+    end
+
+    # list of all params to encrypt on serialization
+    def encrypted_params
+      params_with(:encrypted)
+    end
+
+    def decrypted val
+      return val if val.to_s == ''
+      Configliere::Crypter.decrypt(val, encrypt_pass)
+    end
+
+    def encrypted(val)
+      return if ( !val )
+      Configliere::Crypter.encrypt(val, encrypt_pass)
+    end
+  end
+
+  class Param
+    include EncryptedParam
+  end
+end
+

data/lib/configliere/environment.rb

@@ -0,0 +1,38 @@
+require 'yaml'
+Configliere.use :define
+module Configliere
+  #
+  # Environment -- load configuration from environment variables
+  #
+  module Environment
+    def environment_variables *envs
+      envs.each do |env|
+        case env
+        when Hash
+          env.each do |env, param|
+            adopt_environment_variable! env, param
+          end
+        else
+          param = env.to_s.downcase.to_sym
+          adopt_environment_variable! env, param
+        end
+      end
+    end
+
+    def adopt_environment_variable! env, param
+      define param, :environment => env
+      val = ENV[env]
+      self[param] = val if val
+    end
+
+    def params_from_environment
+      definitions_for(:environment)
+    end
+  end
+
+  Param.class_eval do
+    # include read / save operations
+    include Environment
+  end
+end
+

data/lib/configliere/param.rb

@@ -0,0 +1,97 @@
+module Configliere
+  #
+  # Hash of fields to store.
+  #
+  # Any field name beginning with 'decrypted_' automatically creates a
+  # counterpart 'encrypted_' field using the encrypt_pass.
+  #
+  class Param < ::Hash
+
+    # Initialize with the encrypt_pass and the initial contents of the hash.
+    #
+    # @example
+    #   # Create a param for a hypothetical database with encrypt_pass "your_mom"
+    #   Configliere::Param.new 'your_mom',
+    #     :username=>"mysql_username", :decrypted_password=>"mysql_password"
+    #
+    def initialize hsh={}
+      super()
+      merge! hsh
+    end
+
+    #
+    # Incorporates the given settings.
+    # alias for deep_merge!
+    # Existing values not given in the hash
+    #
+    # @param hsh the defaults to set.
+    #
+    # @example
+    #    Settings.defaults :hat => :cat, :basket => :lotion, :moon => { :man => :smiling }
+    #    Settings.defaults :basket => :tasket, :moon => { :cow => :smiling }
+    #    Config  #=> { :hat => :cat, :basket => :tasket, :moon => { :man => :smiling, :cow => :jumping } }
+    #
+    def defaults hsh
+      deep_merge! hsh
+    end
+
+    # Finalize and validate params
+    def resolve!
+      begin ; super() ; rescue NoMethodError ; nil ; end
+      validate!
+    end
+    # Check that all defined params are valid
+    def validate!
+      begin ; super() ; rescue NoMethodError ; nil ; end
+    end
+
+    def []= param, val
+      if param =~ /\./
+        return deep_set( *( dotted_to_deep_keys(param) | [val] ))
+      else
+        super param.to_sym, val
+      end
+    end
+
+    def [] param
+      if param =~ /\./
+        return deep_get( *dotted_to_deep_keys(param) )
+      else
+        super param.to_sym
+      end
+    end
+
+    def delete param
+      if param =~ /\./
+        return deep_delete( *dotted_to_deep_keys(param) )
+      else
+        super param.to_sym
+      end
+    end
+
+    # returns an actual Hash, not a Param < Hash
+    def to_hash
+      {}.merge! self
+    end
+
+    def use *args
+      Configliere.use *args
+    end
+
+  protected
+    # turns a dotted param ('moon.cheese.type') into
+    # an array of sequential keys for deep_set and deep_get
+    def dotted_to_deep_keys dotted
+      dotted.to_s.split(".").map{|key| key.to_sym}
+    end
+
+    # simple (no-arg) method_missing callse
+    def method_missing meth, *args
+      if args.empty? && meth.to_s =~ /^\w+$/
+        self[meth]
+      elsif args.size == 1 && meth.to_s =~ /^(\w+)=$/
+        self[$1] = args.first
+      else super(meth, *args) end
+    end
+  end
+end

data/lib/configliere/param_store.rb

@@ -0,0 +1,70 @@
+require 'yaml'
+module Configliere
+  #
+  # ParamStore -- load configuration from a simple YAML file
+  #
+  module ParamStore
+    # Load params from disk.
+    # * file is in YAML format, as a hash of handle => param_hash pairs
+    # * filename defaults to ParamStore::DEFAULT_CONFIG_FILE (~/.configliere, probably)
+    def read handle
+      filename = filename_for_handle(handle)
+      begin
+        params = YAML.load(File.open(filename)) || {}
+      rescue Errno::ENOENT => e
+        warn "Loading empty configliere settings file #{filename}"
+        params = {}
+      end
+      params = params[handle] if handle.is_a?(Symbol)
+      deep_merge! params
+    end
+
+    # save to disk.
+    # * file is in YAML format, as a hash of handle => param_hash pairs
+    # * filename defaults to ParamStore::DEFAULT_CONFIG_FILE (~/.configliere, probably)
+    def save! handle
+      filename = filename_for_handle(handle)
+      if handle.is_a?(Symbol)
+        ParamStore.merge_into_yaml_file filename, handle, self.export
+      else
+        ParamStore.write_yaml_file filename, self.export
+      end
+    end
+
+  protected
+
+    # form suitable for serialization to disk
+    # (e.g. the encryption done in configliere/encrypted)
+    def export
+      to_hash
+    end
+
+    def self.write_yaml_file filename, hsh
+      File.open(filename, 'w'){|f| f << YAML.dump(hsh) }
+    end
+
+    def self.merge_into_yaml_file filename, handle, params
+      begin
+        all_settings = YAML.load(File.open(filename)) || {}
+      rescue Errno::ENOENT => e;
+        all_settings = {}
+      end
+      all_settings[handle] = params
+      write_yaml_file filename, all_settings
+    end
+
+    def filename_for_handle handle
+      case
+      when handle.is_a?(Symbol) then Configliere::DEFAULT_CONFIG_FILE
+      when handle.include?('/') then handle
+      else                           File.join(Configliere::DEFAULT_CONFIG_DIR, handle)
+      end
+    end
+
+  end
+
+  Param.class_eval do
+    # include read / save operations
+    include ParamStore
+  end
+end