conker 0.11.0

data/Gemfile

@@ -0,0 +1,3 @@
+source :rubygems
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,32 @@
+PATH
+  remote: .
+  specs:
+    conker (0.11.0)
+      activesupport
+      addressable
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (3.2.9)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    addressable (2.3.2)
+    diff-lcs (1.1.3)
+    i18n (0.6.1)
+    multi_json (1.5.0)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  conker!
+  rspec

data/LICENSE.MIT

@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2010-2013 Sam Stokes, Conrad Irwin, Lee Mallabone,
+Martin Kleppmann
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/conker.gemspec

@@ -0,0 +1,16 @@
+Gem::Specification.new do |s|
+  s.name = 'conker'
+  s.authors = ['Sam Stokes', 'Conrad Irwin', 'Lee Mallabone', 'Martin Kleppmann']
+  s.email = 'supportive@rapportive.com'
+  s.version = '0.11.0'
+  s.summary = %q{Conker will conquer your config.}
+  s.description = "Configuration library."
+  s.homepage = "https://github.com/rapportive/conker"
+  s.license = 'MIT'
+  s.date = Date.today.to_s
+  s.files = `git ls-files`.split("\n")
+  s.require_paths = %w(lib)
+  s.add_dependency 'activesupport'
+  s.add_dependency 'addressable'
+  s.add_development_dependency 'rspec'
+end

data/lib/conker.rb

@@ -0,0 +1,191 @@
+require 'active_support/core_ext/hash/indifferent_access'
+require 'active_support/core_ext/hash/keys'
+require 'active_support/core_ext/hash/reverse_merge'
+require 'addressable/uri'
+
+# Example use:
+#     module Conker
+#       setup_config!(Rails.env, :A_SECRET => api_credential)
+#     end
+module Conker
+  ENVIRONMENTS = %w(production development test)
+  DUMMY_API_KEY = 'dummy_api_key'.freeze
+  DUMMY_CRYPTO_SECRET = 'dummysecretdummysecretdummysecretdummysecretdummysecretdummysecretdummysecre'
+
+  class Error < StandardError; end
+  class MustBeDefined < Error
+    def initialize; super('must be defined'); end
+  end
+  class UnknownType < Error
+    def initialize(type); super("unknown type #{type}"); end
+  end
+  class MissingDefault < Error
+    def initialize; super("missing default value"); end
+  end
+
+
+  class << self
+    # Parse a multi-key hash into globals and raise an informative error message on failure.
+    def setup_config!(current_env, hash)
+      errors = []
+      hash.each do |varname, declaration|
+        begin
+          Kernel.const_set(varname, declaration.evaluate(current_env, varname.to_s))
+        rescue => error
+          errors << [varname, error.message]
+        end
+      end
+
+      error_message = errors.sort_by {|v, e| v.to_s }.map do |varname, error|
+        varname.to_s + ': ' + error
+      end.join(", ")
+      raise Error, error_message unless errors.empty?
+    end
+
+    # A wrapper around setup_config! that uses ENV["RACK_ENV"] || 'development'
+    def setup_rack_environment!(hash)
+      ENV["RACK_ENV"] ||= 'development'
+
+      setup_config!(ENV["RACK_ENV"],
+                    hash.merge(:RACK_ENV => required_in_production(:development => 'development', :test => 'test')))
+    end
+
+    # Declare an environment variable that is required to be defined in the
+    # production environment, and defaults to other values in the test or
+    # development environments.
+    #
+    # You must either specify a :default, or specify defaults for each of
+    # :test and :development.
+    def required_in_production(declaration_opts={})
+      VariableDeclaration.new(declaration_opts.reverse_merge(:required_in => :production))
+    end
+
+    # Declare an environment variable to be used as a credential for accessing
+    # an external API (e.g. username, password, API key, access token):
+    # shorthand for
+    # +required_in_production(:type => :string, :default => 'dummy_api_key')+
+    def api_credential(declaration_opts={})
+      required_in_production({
+        :type => :string,
+        :default => DUMMY_API_KEY,
+      }.merge(declaration_opts))
+    end
+
+    # Declare an environment variable to be used as a secret key by some
+    # encryption algorithm used in our code.
+    #
+    # To generate a secret suitable for production use, try:
+    #   openssl rand -hex 256
+    # (which will generate 256 bytes = 2048 bits of randomness).
+    #
+    # The distinction between this and api_credential is mainly for
+    # documentation purposes, but they also have different defaults.
+    def crypto_secret(declaration_opts={})
+      required_in_production({
+        :type => :string,
+        :default => DUMMY_CRYPTO_SECRET,
+      }.merge(declaration_opts))
+    end
+
+    # A redis url is required_in_production with development and test defaulting to localhost.
+    def redis_url(opts={})
+      required_in_production({
+        :development => "redis://localhost/1",
+        :test => "redis://localhost/3"
+      }.merge(opts))
+    end
+
+    # Declare an environment variable, defaulting to other values if not defined.
+    #
+    # You must either specify a :default, or specify defaults for each of
+    # :production, :test and :development.
+    def optional(declaration_opts = {})
+      VariableDeclaration.new(declaration_opts)
+    end
+  end
+
+
+  class VariableDeclaration
+    def initialize(declaration_opts)
+      declaration_opts.assert_valid_keys :required_in, :type, :default, *ENVIRONMENTS.map(&:to_sym)
+      @declaration_opts = declaration_opts.with_indifferent_access
+    end
+
+    def evaluate(current_environment, varname)
+      @environment = current_environment
+      check_missing_value! varname
+      check_missing_default!
+      from_config_variable_or_default(varname)
+    end
+
+    private
+    def check_missing_value!(varname)
+      if required_in_environments.member?(@environment.to_sym) && !ENV[varname]
+        raise MustBeDefined
+      end
+    end
+
+    def check_missing_default!
+      environments_needing_default = ENVIRONMENTS.map(&:to_sym) - required_in_environments
+      default_specified = @declaration_opts.key? :default
+      all_environments_defaulted = environments_needing_default.all?(&@declaration_opts.method(:key?))
+      unless default_specified || all_environments_defaulted
+        raise MissingDefault
+      end
+    end
+
+    def from_config_variable_or_default(varname)
+      if ENV[varname] && @environment != 'test'
+        interpret_value(ENV[varname], @declaration_opts[:type])
+      else
+        default_value
+      end
+    end
+
+    def required_in_environments
+      Array(@declaration_opts[:required_in]).map(&:to_sym)
+    end
+
+    # Only interpret the default value if it is a string
+    # (to avoid coercing nil to '')
+    def default_value
+      default = @declaration_opts.include?(@environment) ? @declaration_opts[@environment] : @declaration_opts[:default]
+      if default.is_a? String
+        interpret_value(default, @declaration_opts[:type])
+      else
+        default
+      end
+    end
+
+    def interpret_value(value, type)
+      type = type.to_sym if type
+      case type
+      when :boolean
+        value.to_s.downcase == "true" || value.to_i == 1
+        # defaults to false if omitted
+      when :integer
+        Integer(value)
+        # defaults to 0 if omitted
+      when :float
+        value ?  Float(value) : 0.0
+        # defaults to 0.0 if omitted
+      when :url
+        raise MustBeDefined if value.nil? # there's nothing sensible to default to
+        require 'uri' unless defined? URI
+        URI.parse(value.to_s)
+      when :addressable
+        raise MustBeDefined if value.nil? # there's nothing sensible to default to
+        require 'addressable' unless defined? Addressable
+        Addressable::URI.parse(value.to_s)
+      when :timestamp
+        raise MustBeDefined if value.nil? # there's nothing sensible to default to.
+        Time.iso8601(value.to_s).utc
+      when :string, nil
+        value.to_s
+        # defaults to '' if omitted
+      else
+        raise UnknownType, type.to_s
+      end
+    end
+  end
+end

data/spec/lib/conker_spec.rb

@@ -0,0 +1,235 @@
+require 'conker'
+
+describe Conker do
+  before :each do
+    @env_vars = ENV.keys
+    @constants = Kernel.constants
+  end
+
+  after :each do
+    # N.B. this doesn't catch if we *changed* any env vars (rather than adding
+    # new ones).
+    (ENV.keys - @env_vars).each {|k| ENV.delete k }
+    # Same caveat doesn't apply here, because Ruby will whinge if we redefine a
+    # constant.
+    (Kernel.constants - @constants).each do |k|
+      Kernel.send :remove_const, k
+    end
+  end
+
+
+  describe 'basic usage' do
+    def setup!(env = :development)
+      Conker.module_eval do
+        setup_config! env,
+                      A_SECRET: api_credential(development: nil),
+                      PORT: required_in_production(type: :integer, default: 42)
+      end
+    end
+
+    it 'exposes declared variables as top-level constants' do
+      setup!
+      ::A_SECRET.should be_nil
+      ::PORT.should == 42
+    end
+
+    it 'does not turn random environment variables into constants' do
+      ENV['PATH'].should_not be_empty
+      setup!
+      expect { ::PATH }.to raise_error(NameError, /PATH/)
+    end
+
+    it 'lets environment variables override environmental defaults' do
+      ENV['A_SECRET'] = 'beefbeefbeefbeef'
+      setup!
+      ::A_SECRET.should == 'beef' * 4
+    end
+
+    it 'throws useful errors if required variables are missing' do
+      ENV['A_SECRET'].should be_nil
+      ENV['PORT'] = '42'
+      expect { setup! :production }.to raise_error(/A_SECRET/)
+    end
+  end
+
+
+  describe 'required variables' do
+    def setup!
+      env = @env # capture it for block scope
+      Conker.module_eval do
+        setup_config! env,
+          APPNAME: optional(default: 'conker'),
+          PORT: required_in_production(type: :integer, default: 3000)
+      end
+    end
+
+    describe 'in development' do
+      before { @env = :development }
+
+      it 'allows optional variables to be missing' do
+        ENV['APPNAME'].should be_nil
+        ENV['PORT'] = '80'
+        expect { setup! }.not_to raise_error
+      end
+
+      it 'allows required_in_production variables to be missing' do
+        ENV['APPNAME'] = 'widget'
+        ENV['PORT'].should be_nil
+        expect { setup! }.not_to raise_error
+      end
+    end
+
+    describe 'in production' do
+      before { @env = :production }
+
+      it 'allows optional variables to be missing' do
+        ENV['APPNAME'].should be_nil
+        ENV['PORT'] = '80'
+        expect { setup! }.not_to raise_error
+      end
+
+      it 'throws a useful error if required_in_production variables are missing' do
+        ENV['APPNAME'] = 'widget'
+        ENV['PORT'].should be_nil
+        expect { setup! }.to raise_error(/PORT/)
+      end
+    end
+  end
+
+
+  describe 'defaults' do
+    def setup!(env = :development)
+      Conker.module_eval do
+        setup_config! env, NUM_THREADS: optional(type: :integer, test: 1, default: 2)
+      end
+    end
+
+    it 'uses the specified value if one is given' do
+      ENV['NUM_THREADS'] = '4'
+      setup!
+      NUM_THREADS.should == 4
+    end
+
+    it 'uses the default value if none is specified' do
+      ENV['NUM_THREADS'].should be_nil
+      setup!
+      NUM_THREADS.should == 2
+    end
+
+    it 'allows overriding defaults for specific environments' do
+      ENV['NUM_THREADS'].should be_nil
+      setup! :test
+      NUM_THREADS.should == 1
+    end
+  end
+
+
+  describe 'typed variables' do
+    describe 'boolean' do
+      def setup_sprocket_enabled!(value_string)
+        ENV['SPROCKET_ENABLED'] = value_string
+        Conker.module_eval do
+          setup_config! :development, :SPROCKET_ENABLED => optional(type: :boolean, default: false)
+        end
+      end
+
+      it 'parses "true"' do
+        setup_sprocket_enabled! 'true'
+        SPROCKET_ENABLED.should be_true
+      end
+
+      it 'parses "false"' do
+        setup_sprocket_enabled! 'false'
+        SPROCKET_ENABLED.should be_false
+      end
+
+      it 'accepts "1" as true' do
+        setup_sprocket_enabled! '1'
+        SPROCKET_ENABLED.should be_true
+      end
+
+      it 'accepts "0" as false' do
+        setup_sprocket_enabled! '0'
+        SPROCKET_ENABLED.should be_false
+      end
+    end
+
+    describe 'integer' do
+      def setup_num_threads!(value_string)
+        ENV['NUM_THREADS'] = value_string
+        Conker.module_eval do
+          setup_config! :development, :NUM_THREADS => optional(type: :integer, default: 2)
+        end
+      end
+
+      it 'parses "42"' do
+        setup_num_threads! '42'
+        NUM_THREADS.should == 42
+      end
+
+      it 'throws an error if the value is not an integer' do
+        expect { setup_num_threads! 'one hundred' }.to raise_error(/one hundred/)
+      end
+    end
+
+    describe 'float' do
+      def setup_log_probability!(value_string)
+        ENV['LOG_PROBABILITY'] = value_string
+        Conker.module_eval do
+          setup_config! :development, :LOG_PROBABILITY => optional(type: :float, default: 1.0)
+        end
+      end
+
+      it 'parses "0.5"' do
+        setup_log_probability! '0.5'
+        LOG_PROBABILITY.should == 0.5
+      end
+
+      it 'throws an error if the value is not a float' do
+        expect { setup_log_probability! 'zero' }.to raise_error(/zero/)
+      end
+    end
+
+    describe 'url' do
+      def setup_api_url!(value_string)
+        ENV['API_URL'] = value_string
+        Conker.module_eval do
+          setup_config! :development, :API_URL => optional(type: :url, default: 'http://example.com/foo')
+        end
+      end
+
+      it 'exposes a URI object, not a string' do
+        setup_api_url! 'http://localhost:4321/'
+        API_URL.host.should == 'localhost'
+      end
+
+      it 'parses the default value too' do
+        setup_api_url! nil
+        API_URL.host.should == 'example.com'
+      end
+    end
+
+    describe 'addressable' do
+      def setup_api_url!(value_string)
+        ENV['API_URL'] = value_string
+        Conker.module_eval do
+          setup_config! :development, :API_URL => optional(type: :addressable, default: 'http://example.com/foo')
+        end
+      end
+
+      it 'exposes an Addressable::URI object, not a string' do
+        setup_api_url! 'http://localhost:4321/'
+        API_URL.host.should == 'localhost'
+      end
+
+      it 'parses the default value too' do
+        setup_api_url! nil
+        API_URL.host.should == 'example.com'
+      end
+    end
+
+    describe 'timestamp' do
+      xit 'seems to have bit rotted'
+    end
+  end
+end

metadata

@@ -0,0 +1,103 @@
+--- !ruby/object:Gem::Specification
+name: conker
+version: !ruby/object:Gem::Version
+  version: 0.11.0
+  prerelease: 
+platform: ruby
+authors:
+- Sam Stokes
+- Conrad Irwin
+- Lee Mallabone
+- Martin Kleppmann
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Configuration library.
+email: supportive@rapportive.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- LICENSE.MIT
+- conker.gemspec
+- lib/conker.rb
+- spec/lib/conker_spec.rb
+homepage: https://github.com/rapportive/conker
+licenses:
+- MIT
+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.19
+signing_key: 
+specification_version: 3
+summary: Conker will conquer your config.
+test_files: []
+has_rdoc: