hierarchical_config 0.1

data/README.markdown

@@ -0,0 +1,105 @@
+## What is it
+
+HierarchicalConfig is a library that implments a strategy for configuring an application in a static, declarative, robust, and intuitive way
+
+## Principles
+
+1. You should not be able to change your config once it's loaded. That's
+   not configuration, that's globals.
+2. You should be able to check in to source control a config file that
+   holds defaults and defines requirements.
+3. You should be able to define defaults accross multiple environments
+   without repeating yourself.
+4. You should be able to change configuration per box based on deploy
+   that does not affect the defaults or requirements that are checked in
+   to source control.
+
+## Usage
+
+1. require 'hierarchical_config'
+2. MY_APP_CONFIG = HierarchicalConfig.load_config( 'config_name', 'config_directory', 'environment_name' )
+
+## How does it work
+
+HierarchicalConfig loads a yaml file from the config directory. Each top
+level name in the yaml file is either a default stanza (for one or more
+environments,) or a specific environment.
+
+It applies least specific rules first and proceeds to most specific. It
+then reads an optional overrides file and does the same. If any REQUIRED
+values have not been overriden by actual values, it raises an exception.
+
+The object that it returns is a deeply nested tree of configuration that
+can't be modified and raises exceptions if you ask for values that it
+doesn't know about.
+
+* No more having environments load without the mail server address
+  configured.
+* No more silent failures and returning nil for something you thought
+  was configured.
+* No more copy and pasting configuration accross environments.
+* No more stupid YAML tricks to dry up your configuration.
+* No more tricky config that changes based on runtime side effects.
+* No more config that is hidden from developers and not in source
+  control (unless you specifically need to.)
+
+## Example
+
+### config/app.yml
+
+    defaults:
+      root:
+        child_a: 1
+        child_b: 2
+        child_c:
+          grandchild_a: 3
+          grandchild_b: 4
+      super_secret_password: !REQUIRED
+
+    defaults[development,test]:
+      super_secret_password: not_that_secret
+
+    development:
+      root:
+        child_b: 8
+
+### config/app-overrides.yml
+
+    production:
+      super_secret_password: cant_trust_dev_with_this_we_symlink_this_file
+
+## Results
+
+### development
+
+    :root: 
+      :child_a: 1
+      :child_b: 8
+      :child_c: 
+        :grandchild_a: 3
+        :grandchild_b: 4
+    :super_secret_password: not_that_secret
+
+### test
+
+    :root: 
+      :child_a: 1
+      :child_b: 2
+      :child_c: 
+        :grandchild_a: 3
+        :grandchild_b: 4
+    :super_secret_password: not_that_secret
+
+### production
+
+    :root: 
+      :child_a: 1
+      :child_b: 2
+      :child_c: 
+        :grandchild_a: 3
+        :grandchild_b: 4
+    :super_secret_password: cant_trust_dev_with_this_we_symlink_this_file
+
+### staging
+
+    RuntimeError: ["app.super_secret_password is REQUIRED for staging"]

data/lib/hierarchical_config.rb

@@ -0,0 +1,110 @@
+require 'ostruct'
+require 'yaml'
+require 'erb'
+require 'set'
+
+module HierarchicalConfig
+  REQUIRED = :REQUIRED
+  YAML.add_builtin_type( 'REQUIRED' ){ REQUIRED }
+
+  class OpenStruct < ::OpenStruct
+    def method_missing( mid, *args ) # :nodoc:
+      mname = mid.id2name
+      len = args.length
+      if mname.chomp!('=')
+        if len != 1
+          raise ArgumentError, "wrong number of arguments (#{len} for 1)", caller(1)
+        end
+        modifiable[new_ostruct_member(mname)] = args[0]
+      elsif len == 0 && @table.key?( mid )
+        @table[mid]
+      else
+        raise NoMethodError, "undefined method `#{mname}' for #{self}", caller(1)
+      end
+    end
+
+    def to_hash
+      @table.inject({}) do |hash, key_value|
+        key, value = *key_value
+        hash[key] = value.respond_to?( :to_hash ) ? value.to_hash : value
+        hash
+      end
+    end
+  end
+
+  class << self
+    def load_config( name, dir, environment )
+      primary_config_file   = "#{dir}/#{name}.yml"
+      overrides_config_file = "#{dir}/#{name}-overrides.yml"
+
+      config_hash = load_hash_for_env( primary_config_file, environment )
+
+      if File.exists?( overrides_config_file )
+        overrides_config_hash = load_hash_for_env( overrides_config_file, environment )
+        config_hash = deep_merge( config_hash, overrides_config_hash )
+      end
+
+      config_hash, errors = lock_down_and_ostructify!( config_hash, name, environment )
+
+      raise errors.inspect unless errors.empty?
+
+      OpenStruct.new(config_hash).freeze
+    end
+
+    def load_hash_for_env( file, environment )
+      yaml_config   = YAML::load(ERB.new(IO.read(file)).result)
+
+      ordered_stanza_labels = []
+      ordered_stanza_labels << 'defaults' if yaml_config.key? 'defaults'
+      ordered_stanza_labels += yaml_config.keys.grep(/^defaults\[.*#{environment}/).sort_by{ |a| a.count(',') }
+      ordered_stanza_labels << environment if yaml_config.key? environment
+
+      config = ordered_stanza_labels.inject({}) do |acc, label|
+        deep_merge( acc, yaml_config[label] )
+      end
+
+    rescue StandardError => e
+      raise <<-ERROR
+        Error loading config from file #{file}.
+        #{$!.inspect}
+        #{$@}
+      ERROR
+    end
+
+    private
+
+    # merges two hashes with nested hashes if present
+    def deep_merge( hash1, hash2 )
+      hash1 = hash1.dup
+      ( hash1.keys + hash2.keys ).each do | key |
+        if hash1.key?( key ) && hash2.key?( key ) &&
+           hash1[key].is_a?( Hash ) && hash2[key].is_a?( Hash )
+           hash1[key] = deep_merge( hash1[key], hash2[key] )
+        elsif hash2.key?( key )
+          hash1[key] = hash2[key]
+        end
+      end
+      hash1
+    end
+
+    # Mutator method that does three things:
+    # * checks if any of the keys were required and not set. Upon finding
+    # it adds key to the error set
+    # * recursively sets open structs for deep hashes
+    # * recursively freezes config objects
+    def lock_down_and_ostructify!( hash, path, environment)
+      errors = []
+      hash.each do | key, value |
+        case
+        when value.respond_to?( :keys ) && value.respond_to?( :values )
+          child_hash, child_errors = lock_down_and_ostructify!( value, path + '.' + key, environment )
+          errors += child_errors
+          hash[key] = OpenStruct.new(child_hash).freeze
+        when value == REQUIRED
+          errors << "#{path}.#{key} is REQUIRED for #{environment}"
+        end
+      end
+      return hash, errors
+    end
+  end
+end

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification
+name: hierarchical_config
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- timgaleckas
+- tjbladez
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2011-11-23 00:00:00.000000000Z
+dependencies: []
+description: Robust strategy for defining the configuration accross environements,
+  machines, clusters
+email: tim@galeckas.com, nick@tjbladez.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/hierarchical_config.rb
+- README.markdown
+homepage: http://github.com/timgaleckas/hierarchical_config
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.11
+signing_key: 
+specification_version: 3
+summary: Robust strategy for defining the configuration accross environements, machines,
+  clusters
+test_files: []