chamber 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: ced47025f0acaf5898cd70cb5d99f17f9c72820c
-  data.tar.gz: d155b92fdd26e2a8328296b677485e0c0d01d77a
+  metadata.gz: 06481d8263ba75487270bf6bc366357d8ea45e81
+  data.tar.gz: 7095ff800b808dae4ba3470fca3cdcab26072ec1
 SHA512:
-  metadata.gz: 950b798ef819faf34cb6319f1f08dd75db210aee8f77de133ed474a178c92c79e954267c2ea96fdb70ee9563863ce76bfec1fff8d9b3de6262f6e2c913f0b866
-  data.tar.gz: 936ea0a71f1f32b4abc36bc0a709bd3770da3f6fda07b068c5c12be9b1c38decf123b570d0b681f7412a6769f13c94262cfbf11f11cf33cae48864ed69f8c283
+  metadata.gz: 5d2971516f0228a5fc17ce2b29375b5fb6fd7475918c9ad6df934727b0e15f7176979e16ce93cb9201cf8b69123485186673d0adcdb000680efb665de5298b0e
+  data.tar.gz: 6f38b25d90ade7a0ddc3a07ecb00a069d4f078994f8edab98567434a48767b6459c2079679132df941528252b50208f4b590fdec3d6c3422aa09e0f1a9721f91

data/.ruby-gemset

@@ -0,0 +1 @@
+chamber

data/.ruby-version

@@ -0,0 +1 @@
+2.0.0-p247

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 2.0.0
+  - 1.9.3
+  - 1.9.2

data/README.md

@@ -1,4 +1,4 @@
-# Chamber
+# Chamber [![Build Status](https://travis-ci.org/stevenhallen/chamber.png)](https://travis-ci.org/stevenhallen/chamber)
 
 Chamber lets you source your Settings from an arbitrary number of YAML files and
 provides a simple mechanism for overriding settings from the ENV, which is
@@ -20,7 +20,193 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+The following instructions are for a Rails app hosted on heroku with both
+staging and production heroku environments.
+
+Create a Settings class that extends Chamber in `app/models/settings.rb`:
+
+```ruby
+class Settings
+  extend Chamber
+end
+```
+
+Create a `config/settings.yml` that has this structure:
+
+```yml
+development:
+  some_setting: value for dev
+  some_password:
+    environment:  ENV_VAR_NAME
+test:
+  some_setting: value for test
+  some_password:
+    environment:  ENV_VAR_NAME
+staging:
+  some_setting: value for staging
+  some_password:
+    environment:  ENV_VAR_NAME
+production:
+  some_setting: value for production
+  some_password:
+    environment:  ENV_VAR_NAME
+```
+
+Call `source` in your Settings class:
+
+```ruby
+class Settings
+  extend Chamber
+
+  source Rails.root.join('config', 'settings.yml'), namespace: Rails.env, override_from_environment: true
+end
+```
+
+Add environment-specific files for development and test to supply the values for
+those environments.  Make sure to add these to .gitignore.
+
+Add another call to `source` for these files:
+
+```ruby
+class Settings
+  extend Chamber
+
+  source Rails.root.join('config', 'settings.yml'), namespace: Rails.env, override_from_environment: true
+  source Rails.root.join('config', "credentials-#{Rails.env}.yml")
+end
+```
+
+Use `heroku config` to set the `ENV_VAR_NAME` value for the staging and
+production remotes.
+
+Now you can access your settings in your code from `Settings.instance` (assuming
+you extended Chamber in a class named `Settings`).
+
+In other words, given a configuration file like this:
+
+```yml
+s3:
+  access_key_id: value
+  secret_access_key: value
+  bucket: value
+```
+
+the corresponding Paperclip configuration would look like this:
+
+```ruby
+Paperclip::Attachment.default_options.merge!(
+  storage: 's3',
+  s3_credentials: {
+    access_key_id: Settings.instance.s3.access_key_id,
+    secret_access_key: Settings.instance.s3.secret_access_key
+  },
+  bucket: Settings.instance.s3.bucket,
+  ...
+```
+
+## General Principles
+
+### Support best practices with sensitive information
+
+Generally this is expressed in this overly simplified form:  "Don't store
+sensitive information in git."  A better way to say it is that you should store
+sensitive information separate from non-sensitive information.  There's nothing
+inherently wrong with storing sensitive information in git.  You just wouldn't
+want to store it in a public repository.
+
+If it weren't for this concern, managing settings would be trivial, easily
+solved use any number of approaches (e.g., [like using YAML and ERB in an
+initializer](http://urgetopunt.com/rails/2009/09/12/yaml-config-with-erb.html).
+
+I recommend adding a pattern like this to `.gitignore`:
+
+```
+# Ignore the environment-specific files that contain the real credentials:
+/config/credentials-*.yml
+
+# But don't ignore the example file that shows the structure:
+!/config/credentials-example.yml
+```
+
+You would then use Chamber like this:
+
+```ruby
+class Settings
+  extend Chamber
+  source Rails.root.join('config', "credentials-#{Rails.env}.yml")
+end
+```
+
+### Support arbitrary organization
+
+You should be able to organize your settings files however you like.  You want
+one big jumbo settings.yml?  You can do that with Chamber.  You want a distinct
+settings file for each specific concern?  You can do that too.
+
+Chamber supports this by allowing:
+
+* Arbitrary number of files:
+
+```ruby
+class Settings
+  extend Chamber
+
+  source Rails.root.join('config', 'settings.yml')
+  source Rails.root.join('config', 'facebook.yml')
+  source Rails.root.join('config', 'twitter.yml')
+  source Rails.root.join('config', 'google-plus.yml')
+end
+```
+
+* Environment-specific filenames (e.g., `settings-#{Rails.env}.yml`)
+
+* Namespaces:
+
+```ruby
+class Settings
+  extend Chamber
+
+  source Rails.root.join('config', 'settings.yml'), namespace: Rails.env
+end
+```
+
+### Support overriding setting values at runtime from ENV
+
+[heroku](http://heroku.com) addons are configured from ENV.  To support this,
+Chamber's `source` method provides an `override_from_environment` option; e.g.,
+
+```ruby
+class Settings
+  extend Chamber
+
+  source Rails.root.join('config', 'settings.yml'), override_from_environment: true
+end
+```
+
+## Ideas
+
+* Add a rake task for validating environments (do all environments have the same
+  settings?)
+
+* Add a rake task for setting Heroku environment variables.
+
+## Alternatives
+
+### figaro
+
+[figaro](https://github.com/laserlemon/figaro)
+
+### idkfa
+
+[idkfa](https://github.com/bendyworks/idkfa)
+
+### settingslogic
+
+[settingslogic](https://github.com/binarylogic/settingslogic)
+
+### Others?
+
+I'd love to hear of other gems and/or approaches to settings!
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,6 @@
-require "bundler/gem_tasks"
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/chamber.gemspec

@@ -24,6 +24,8 @@ CHAMBER
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
+  spec.add_runtime_dependency "hashie", "~> 2.0"
+
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec", "~> 2.14"

data/lib/chamber.rb

@@ -1,5 +1,84 @@
-require "chamber/version"
+require 'erb'
+require 'hashie'
+require 'yaml'
+
+require 'chamber/version'
 
 module Chamber
-  # Your code goes here...
+  class ChamberInvalidOptionError < ArgumentError; end
+
+  def source(filename, options={})
+    assert_valid_keys(options)
+
+    add_source(filename, options)
+  end
+
+  def load!
+    sources.each do |source|
+      filename, options = source
+
+      load_source!(filename, options)
+    end
+  end
+
+  def clear!
+    @chamber_instance = nil
+    @chamber_sources = nil
+  end
+
+  def reload!
+    @chamber_instance = nil
+    load!
+  end
+
+  def instance
+    @chamber_instance ||= Hashie::Mash.new
+  end
+
+private
+
+  def assert_valid_keys(options)
+    unknown_keys = options.keys - [:namespace, :override_from_environment]
+
+    raise(ChamberInvalidOptionError, options) unless unknown_keys.empty?
+  end
+
+  def sources
+    @chamber_sources ||= []
+  end
+
+  def add_source(filename, options)
+    sources << [filename, options]
+  end
+
+  def load_source!(filename, options)
+    return unless File.exists?(filename)
+
+    hash = hash_from_source(filename, options[:namespace])
+    if options[:override_from_environment]
+      override_from_environment!(hash)
+    end
+
+    instance.deep_merge!(hash)
+  end
+
+  def hash_from_source(filename, namespace)
+    contents = open(filename).read
+    hash = YAML.load(ERB.new(contents).result).to_hash || {}
+    hash = Hashie::Mash.new(hash)
+
+    namespace ? hash.fetch(namespace) : hash
+  end
+
+  def override_from_environment!(hash)
+    hash.each_pair do |key, value|
+      next unless value.is_a?(Hash)
+
+      if value.environment
+        hash[key] = ENV[value.environment]
+      else
+        override_from_environment!(value)
+      end
+    end
+  end
 end

data/lib/chamber/version.rb

@@ -1,3 +1,3 @@
 module Chamber
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/lib/chamber_spec.rb

@@ -0,0 +1,224 @@
+require 'spec_helper'
+
+require 'tempfile'
+
+class Settings
+  extend Chamber
+end
+
+describe Chamber do
+  before do
+    Settings.clear!
+  end
+
+  describe '.source' do
+    context 'when an invalid option is specified' do
+      let(:options) do
+        { foo: 'bar' }
+      end
+
+      it 'raises ChamberInvalidOptionError' do
+        expect { Settings.source('filename', options) }.to raise_error(Chamber::ChamberInvalidOptionError)
+      end
+    end
+
+    context 'when no options are specified' do
+      it 'does not raise an error' do
+        expect { Settings.source('filename') }.not_to raise_error
+      end
+    end
+
+    context 'when valid options are specified' do
+      context 'and options only contains :namespace' do
+        let(:options) do
+          { namespace: 'bar' }
+        end
+
+        it 'does not raise an error' do
+          expect { Settings.source('filename', options) }.not_to raise_error
+        end
+      end
+
+      context 'and options only contains :override_from_environment' do
+        let(:options) do
+          { override_from_environment: 'bar' }
+        end
+
+        it 'does not raise an error' do
+          expect { Settings.source('filename', options) }.not_to raise_error
+        end
+      end
+
+      context 'and options contains both :namespace and :override_from_environment' do
+        let(:options) do
+          {
+            namespace: 'bar',
+            override_from_environment: 'bar'
+          }
+        end
+
+        it 'does not raise an error' do
+          expect { Settings.source('filename', options) }.not_to raise_error
+        end
+      end
+    end
+  end
+
+  describe '.load!' do
+    context 'when a non-existent file is specified' do
+      let(:file) { Tempfile.new('test') }
+      let!(:filename) { file.path }
+
+      before do
+        file.close
+        file.unlink
+        expect(File.exists?(filename)).to be_false
+        Settings.source filename
+      end
+
+      it 'does not raise an error' do
+        expect { Settings.load! }.not_to raise_error
+      end
+
+      it 'leaves the instance empty' do
+        Settings.load!
+        expect(Settings.instance).to be_empty
+      end
+    end
+
+    context 'when an existing file is specified' do
+      let(:file) { Tempfile.new('test') }
+      let(:filename) { file.path }
+      let(:content) do
+        <<-CONTENT
+secret:
+  environment: CHAMBER_TEST
+development:
+  foo: bar dev
+test:
+  foo: bar test
+CONTENT
+      end
+
+      before do
+        file.write(content)
+        file.close
+      end
+
+      after do
+        file.unlink
+      end
+
+      context 'and no options are specified' do
+        before { Settings.source(filename) }
+
+        let(:expected) do
+          {
+            'secret' => {
+              'environment' => 'CHAMBER_TEST'
+            },
+            'development' => {
+              'foo' => 'bar dev'
+            },
+            'test' => {
+              'foo' => 'bar test'
+            }
+          }
+        end
+
+        it 'loads all settings' do
+          Settings.load!
+          expect(Settings.instance.to_hash).to eq expected
+        end
+      end
+
+      context 'and the :namespace option is specified' do
+        before { Settings.source(filename, namespace: namespace) }
+
+        context 'and it is valid' do
+          let(:namespace) { 'development' }
+          let(:expected) do
+            {
+              'foo' => 'bar dev'
+            }
+          end
+
+          it 'loads settings for the specified namespace' do
+            Settings.load!
+            expect(Settings.instance.to_hash).to eq expected
+          end
+        end
+
+        context 'and it is not valid' do
+          let(:namespace) { 'staging' }
+
+          it 'raises a KeyError' do
+            expect { Settings.load! }.to raise_error(KeyError)
+          end
+        end
+      end
+
+      context 'and the :override_from_environment option is specified' do
+        before { Settings.source(filename, override_from_environment: true) }
+
+        context 'and the environment variable is present' do
+          before { ENV['CHAMBER_TEST'] = 'value' }
+
+          it 'overrides the settings from the environment' do
+            Settings.load!
+            expect(Settings.instance.secret).to eq 'value'
+          end
+        end
+
+        context 'and the environment variable is not present' do
+          before { ENV.delete('CHAMBER_TEST') }
+
+          it 'sets the value to nil' do
+            Settings.load!
+            expect(Settings.instance.secret).to be_nil
+          end
+        end
+      end
+    end
+  end
+
+  describe '.reload!' do
+    context 'when a filename is changed after it is sourced and loaded' do
+      let(:file) { Tempfile.new('test') }
+      let!(:filename) { file.path }
+      let(:content) do
+        <<-CONTENT
+initial: value
+CONTENT
+      end
+      let(:modified) do
+        <<-MODIFIED
+modified: changed
+MODIFIED
+      end
+
+      before do
+        file.write(content)
+        file.close
+        Settings.source(filename)
+        Settings.load!
+      end
+
+      after do
+        file.unlink
+      end
+
+      it 'reloads the settings' do
+        File.open(filename, 'w') { |writer| writer.write(modified) }
+
+        expect { Settings.reload! }.to change { Settings.instance.to_hash }.from({ 'initial' => 'value' }).to({ 'modified' => 'changed' })
+      end
+    end
+  end
+
+  describe '.instance' do
+    it 'is a Hashie::Mash' do
+      expect(Settings.instance).to be_a(Hashie::Mash)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -2,3 +2,11 @@ require 'simplecov'
 SimpleCov.start
 
 require 'rspec'
+require 'chamber'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.filter_run focused: true
+  config.alias_example_to :fit, focused: true
+  config.run_all_when_everything_filtered = true
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: chamber
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - stevenhallen
@@ -9,8 +9,22 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-29 00:00:00.000000000 Z
+date: 2013-11-15 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: hashie
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -79,6 +93,9 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
+- .ruby-gemset
+- .ruby-version
+- .travis.yml
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -86,6 +103,7 @@ files:
 - chamber.gemspec
 - lib/chamber.rb
 - lib/chamber/version.rb
+- spec/lib/chamber_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/stevenhallen/chamber
 licenses:
@@ -107,9 +125,11 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.1.10
+rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: Heroku-friendly Settings
 test_files:
+- spec/lib/chamber_spec.rb
 - spec/spec_helper.rb
+has_rdoc: