greenpeace 0.0.2 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4f258d970be062302715c418752c671084b05da0
-  data.tar.gz: 2439df02a266bbcaed7523c3c054a62f9dd47ad5
+  metadata.gz: 1de449972c8785c764cf0f29f1d3776c3ccb4200
+  data.tar.gz: cbbe27c9e0ee871c4b40139b4f96de246d5cd12a
 SHA512:
-  metadata.gz: b318de0b7cf80a8e49b8841cf96e97ad0e542f72e5967c233bfedb9f9d53ada29f675f669a2a861191a13a7669d6407bd2041d619bc05a42ba3c7549e2d915a6
-  data.tar.gz: c593c461ef671e37075b7b53396c4d9afff7498abb5eb5bc442cd3982171816ed7d76f80cbd0dcddc61ccae6173268c0f976770f4e4c51d088c4f2e199d3534d
+  metadata.gz: 7e84ee0f0c2bb15dee1b8f585e0edb74621e2c5679e8f50beff7140d1a6d6f904718a0a826a98a1b97e141695c342f9189f9163fad1c0dda45b823c40a6d2905
+  data.tar.gz: a7a4dab7dc2a825c1063c7a29db8f43799dadfd158cb186da939afd0a9c10844e93f9d1e8e5f63f459357e8e7f88322c86745b99b743f538915cdd6b32550b33

data/README.md

@@ -0,0 +1,111 @@
+# Greenpeace
+
+**Greenpeace** is a small environment checker for [12 factor
+apps](http://12factor.net/config).
+
+## Why?
+
+One of the factors in a [12 factor app](http://12factor.net) is configuration
+management. The recommended approach is using environment variables to provide
+configuration values to the application.
+
+While the approach works great, we found some limitations and itches with it:
+
+* There is no way to check if the environment has been correctly configured on
+  application startup. This delays deployment and configuration errors until
+the moment the configuration key is required.
+
+* Accessing configuration values through the ruby `ENV` hash is a bit
+  cumbersome, and does not provide typecasting.
+
+There are some gems already out there that solve these, but none of them fixed
+them how we wanted them to. See the similarities section bellow.
+
+**Greenpeace** solves this in a simple, straightforward way. It is an
+environment checker that checks that the environment contains all the required
+values. It also exposes ENV values through a simple configuration API so you
+can do `Greenpeace.env.port` instead of `ENV['PORT'].to_i`, applying
+typecasting as required.
+
+## Usage
+
+### Installation
+
+Add the gem to your Gemfile:
+
+~~~ruby
+gem "greenpeace"
+~~~
+
+Run bundle to install the engine:
+
+~~~
+> bundle install
+~~~
+
+### Usage
+
+You need to setup your environment in a ruby file of your liking. If you are
+using rails, the gem automatically loads a file at `config/greenpeace.rb` where
+you should configure your requirements using the provided API. Otherwise, put
+those requirements somewhere and ensure they are run before starting your
+application.
+
+The API is declarative and quite simple to read and write:
+
+~~~ruby
+Greenpeace.configure do |env|
+  # You can mark a key to be required for boot.
+  env.requires :database_url
+
+  # You can mark a key as an optional value, with a default if it is not
+  # defined.
+  env.may_have :google_analytics_account, default: "UA-xxxxx"
+
+  # You can mark required or optional keys to be converted to a type when
+  # reading the values. Valid types are :string and :int
+  env.requires :port, type: :int
+  env.may_have :api_timeout, type: :int, default: 30
+
+  # You can add an optional message which describes what the key is about, for
+  # documenting configuration options. This documentation string is used when
+  # raising an initialization exception if the key is not found, or if the
+  # type is not correct.
+  env.requires 'API_KEY', doc: "API key for the Frumboloizer service"
+end
+~~~
+
+Whenever the `configure` method is called (which is done automatically on
+rails), Greenpeace will check the environment and raise exceptions if something
+is not correctly configured. In addition to this, you can now access the
+configured keys through a simple API:
+
+~~~ruby
+  if Greenpeace.env.use_google_analytics
+    # ...
+  end
+~~~
+
+## License
+
+Copyright (C) 2014 Recompensa.mobi
+
+
+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/lib/greenpeace/configuration/config.rb

@@ -1,46 +1,109 @@
-require "greenpeace/configuration/key"
-require "greenpeace/configuration/type"
-require "greenpeace/configuration/doc"
-require "greenpeace/configuration/default"
-require "greenpeace/configuration/requirement"
-require "greenpeace/configuration/option"
-
-class Greenpeace::Configuration::Config
-  attr_reader :requirements
-  attr_reader :options
-
-  def initialize
-    @requirements = []
-    @options = []
-  end
+require 'greenpeace/configuration/key'
+require 'greenpeace/configuration/type'
+require 'greenpeace/configuration/doc'
+require 'greenpeace/configuration/default'
+require 'greenpeace/configuration/requirement'
+require 'greenpeace/configuration/option'
 
-  def requires(key, options={})
-    requirement = Greenpeace::Configuration::Requirement.new(key, options)
-    add_requirement(requirement)
-  end
+module Greenpeace
+  module Configuration
+    #
+    # = Config
+    #
+    # This class exposes the API methods that the end user can call on a
+    # `Greenpeace.configure` block.
+    #
+    # == Requirements
+    #
+    # Requirements are definition of environment keys which MUST be present on
+    # application startup. When a requirement is defined, if the environment
+    # key is not present and the current runtime mode does not have a specific
+    # default for the key an error is raised.
+    #
+    # The API is like the following:
+    #
+    #   env.requires :key,
+    #     type: TYPE,
+    #     doc: DOC,
+    #     defaults: DEFAULTS
+    #
+    # This defines a required value on ENV['KEY']. Everything after the key is
+    # absolutely optional:
+    #
+    # * TYPE: Type to convert the env value to. May be either :string or :int.
+    # :string by default.
+    #
+    # * DOC: Doc string which will be used when raising the exception if the
+    # environment value is not present. Extremely useful to make your
+    # application self-describing.
+    #
+    # * DEFAULTS: Hash which defines special defaults to use when the
+    # environment value is not present on a specific runtime mode. For example,
+    # if you want an entry to raise an error on production, but default to a
+    # given value on development, you declare a requirement like this:
+    #
+    #   env.requires :port, type: :int, defaults: { development: 3000 }
+    #
+    # == Options
+    #
+    # Options are definition of environment keys which may or may not be
+    # present on application startup. Think of them as configurable optional
+    # values. When an option is defined, the environment value is used first,
+    # if any. If not, a default value is provided instead.
+    #
+    # The API is like this:
+    #
+    #   env.may_have :key,
+    #     type: TYPE,
+    #     doc: DOC,
+    #     default: DEFAULT,
+    #     defaults: DEFAULTS
+    #
+    # The TYPE, DOC and DEFAULTS options work just like in the case of
+    # requirements. The main difference is in the DEFAULT value, which is used
+    # if no value is present in the environment, and no default is defined in
+    # the DEFAULTS entry for the current runtime mode. By default, if no value
+    # is present in the environment hash, no value is provided in the DEFAULT
+    # option and no value is provided in the DEFAULTS option for the current
+    # runtime environment, nil is returned.
+    class Config
+      attr_reader :settings
 
-  def may_have(key, options={})
-    option = Greenpeace::Configuration::Option.new(key, options)
-    add_option(option)
-  end
+      def initialize(environment = '')
+        @settings = []
+        @environment = environment
+      end
 
-  private
-  def add_requirement(requirement)
-    if key_already_defined?(requirement.key)
-      raise "Requirement key #{requirement.key} must be uniquely defined"
-    end
-    @requirements << requirement
-  end
+      def requires(key, options = {})
+        requirement = Greenpeace::Configuration::Requirement.new(
+          key,
+          options,
+          @environment)
 
-  def add_option(option)
-    if key_already_defined?(option.key)
-      raise "Option key #{option.key} must be uniquely defined"
-    end
-    @options << option
-  end
+        add_setting_uniquely(requirement)
+      end
+
+      def may_have(key, options = {})
+        option = Greenpeace::Configuration::Option.new(
+          key,
+          options,
+          @environment)
+
+        add_setting_uniquely(option)
+      end
 
-  def key_already_defined?(key)
-    @requirements.any? {|item| item.key == key} ||
-      @options.any? {|item| item.key == key}
+      private
+
+      def add_setting_uniquely(setting)
+        if key_already_defined?(setting.key)
+          fail "Duplicated configuration key #{setting.key}"
+        end
+        @settings << setting
+      end
+
+      def key_already_defined?(key)
+        @settings.any? { |setting| setting.key == key }
+      end
+    end
   end
 end

data/lib/greenpeace/configuration/default.rb

@@ -1,18 +1,54 @@
-module Greenpeace::Configuration
-  class Default
-    attr_reader :value
+module Greenpeace
+  module Configuration
+    # Defines a default setting in a requirement or option
+    class Default
+      def initialize(type, options, key, plural_key)
+        @type = type
 
-    def initialize(type, options, key)
-      @type = type
-      @value = options.has_key?(key) ? validate_default(options[key]) : nil
-    end
+        @has_direct_value = options.key?(key)
+        @direct_value = extract_direct_value(options, key)
+
+        @has_environment_value = options.key?(plural_key)
+        @environment_values = extract_environment_value(options, plural_key)
+      end
+
+      def value(environment)
+        if @has_direct_value
+          @direct_value
+        elsif @has_environment_value
+          @environment_values[environment.to_s]
+        else
+          nil
+        end
+      end
+
+      def environment_value?(environment)
+        @has_environment_value && @environment_values[environment.to_s]
+      end
+
+      private
+
+      def validate_environment_hash(hash)
+        hash.keys.each_with_object({}) do |key, result|
+          result[key.to_s] = validate_default(hash[key])
+        end
+      end
+
+      def validate_default(value)
+        unless @type.valid_value?(value)
+          fail "Default value #{value}" \
+            " is not of the corresponding type #{@type}"
+        end
+        value
+      end
+
+      def extract_direct_value(options, key)
+        validate_default(options[key]) if @has_direct_value
+      end
 
-    private
-    def validate_default(value)
-      unless @type.valid_value?(value)
-        raise "Default value #{value} is not of the corresponding type #{@type}"
+      def extract_environment_value(options, plural_key)
+        validate_environment_hash(options[plural_key]) if @has_environment_value
       end
-      value
     end
   end
 end

data/lib/greenpeace/configuration/doc.rb

@@ -1,19 +1,22 @@
-module Greenpeace::Configuration
-  class Doc
+module Greenpeace
+  module Configuration
+    # Represents a doc configuration in a requirement
+    class Doc
+      def initialize(options, key)
+        @doc = options.key?(key) ? validate_doc(options[key]) : 'Undefined'
+      end
 
-    def initialize(options, key)
-      @doc = options.has_key?(key) ? validate_doc(options[key]) : "Undefined"
-    end
+      def to_s
+        @doc
+      end
 
-    def to_s
-      @doc
-    end
+      private
 
-    private
-    def validate_doc(doc)
-      raise "Doc cannot be nil" if doc.nil?
-      raise "Doc must be a string" unless doc.is_a?(String)
-      doc
+      def validate_doc(doc)
+        fail 'Doc cannot be nil' if doc.nil?
+        fail 'Doc must be a string' unless doc.is_a?(String)
+        doc
+      end
     end
   end
 end

data/lib/greenpeace/configuration/key.rb

@@ -1,36 +1,41 @@
-module Greenpeace::Configuration
-  class Key
-    def initialize(key)
-      @key = validate_key(key)
-    end
+module Greenpeace
+  module Configuration
+    # Represents an environment key in a configuration entry
+    class Key
+      def initialize(key)
+        @key = validate_key(key)
+      end
 
-    def ==(other)
-      other.raw_key == raw_key
-    end
+      def ==(other)
+        other.key == @key
+      end
 
-    def to_s
-      @key
-    end
+      def to_s
+        @key.to_s
+      end
 
-    def identifier
-      @key.downcase
-    end
+      def identifier
+        @key.to_s
+      end
 
-    def env_identifier
-      @key
-    end
+      def env_identifier
+        @key.to_s.upcase
+      end
 
-    protected
-    def raw_key
-      @key
-    end
+      protected
+
+      attr_reader :key
+
+      private
 
-    private
-    def validate_key(key)
-      raise "Key cannot be nil" if key.nil?
-      raise "Key #{key} must be a string, but was a #{key.class}" unless key.is_a? String
-      raise "Key cannot be blank" if key.empty?
-      key
+      def validate_key(key)
+        fail 'Key cannot be nil' if key.nil?
+        unless key.is_a? Symbol
+          fail "Key #{key} must be a symbol, but was a #{key.class}"
+        end
+        fail 'Key cannot be blank' if key.empty?
+        key
+      end
     end
   end
 end

data/lib/greenpeace/configuration/option.rb

@@ -1,27 +1,37 @@
-module Greenpeace::Configuration
-  class Option
-    attr_reader :key
-    attr_reader :type
-    attr_reader :doc
-    attr_reader :default
+require 'greenpeace/configuration/key'
+require 'greenpeace/configuration/type'
+require 'greenpeace/configuration/doc'
+require 'greenpeace/configuration/default'
 
-    def initialize(key, options)
-      @key = Greenpeace::Configuration::Key.new(key)
-      @type = Greenpeace::Configuration::Type.new(options, :type)
-      @doc = Greenpeace::Configuration::Doc.new(options, :doc)
-      @default = Greenpeace::Configuration::Default.new(@type, options, :default)
-    end
+module Greenpeace
+  module Configuration
+    # Represents an environment option
+    class Option
+      attr_reader :key
 
-    def identifier
-      @key.identifier
-    end
+      def initialize(key, options, environment)
+        @environment = environment
+        @key = Greenpeace::Configuration::Key.new(key)
+        @type = Greenpeace::Configuration::Type.new(options, :type)
+        @doc = Greenpeace::Configuration::Doc.new(options, :doc)
+        @default = Greenpeace::Configuration::Default.new(
+          @type,
+          options,
+          :default,
+          :defaults)
+      end
+
+      def identifier
+        @key.identifier
+      end
 
-    def value
-      value = ENV[@key.env_identifier]
-      if value.nil? or value.empty?
-        @default.value
-      else
-        @type.convert(value)
+      def value
+        value = ENV[@key.env_identifier]
+        if value.nil? || value.empty?
+          @default.value(@environment)
+        else
+          @type.convert(value)
+        end
       end
     end
   end

data/lib/greenpeace/configuration/requirement.rb

@@ -1,26 +1,50 @@
-module Greenpeace::Configuration
-  class Requirement
-    attr_reader :key
-    attr_reader :type
-    attr_reader :doc
+require 'greenpeace/configuration/key'
+require 'greenpeace/configuration/type'
+require 'greenpeace/configuration/doc'
+require 'greenpeace/configuration/default'
 
-    def initialize(key, options)
-      @key = Greenpeace::Configuration::Key.new(key)
-      @type = Greenpeace::Configuration::Type.new(options, :type)
-      @doc = Greenpeace::Configuration::Doc.new(options, :doc)
-    end
+module Greenpeace
+  module Configuration
+    # Represents an environment requirement
+    class Requirement
+      attr_reader :key
 
-    def identifier
-      @key.identifier
-    end
+      def initialize(key, options, environment)
+        @environment = environment
+        @key = Greenpeace::Configuration::Key.new(key)
+        @type = Greenpeace::Configuration::Type.new(options, :type)
+        @doc = Greenpeace::Configuration::Doc.new(options, :doc)
+        @default = Greenpeace::Configuration::Default.new(
+          @type,
+          options,
+          nil,
+          :defaults)
+      end
+
+      def identifier
+        @key.identifier
+      end
+
+      def value
+        value = ENV[@key.env_identifier]
 
-    def value
-      value = ENV[@key.env_identifier]
-      if value.nil? or value.empty?
-        raise "Environment key [#{@key}] is missing. The key documentation: #{@doc}"
+        if value.nil? || value.empty?
+          try_with_environment_values
+        else
+          @type.convert(value)
+        end
       end
 
-      @type.convert(value)
+      private
+
+      def try_with_environment_values
+        if @default.environment_value?(@environment)
+          @default.value(@environment)
+        else
+          fail "Environment key [#{@key}] is missing." \
+            "The key documentation: #{@doc}"
+        end
+      end
     end
   end
 end

data/lib/greenpeace/configuration/type.rb

@@ -1,51 +1,56 @@
-module Greenpeace::Configuration
-  class Type
-    TYPES = {
-      string: {
-        converter: :to_s,
-        typeclass: String,
-        regexp: /.*/
-      },
-
-      int: {
-        converter: :to_i,
-        typeclass: Integer,
-        regexp: /\d+/
-      },
-    }
-
-    def initialize(options, key)
-      @type = options.has_key?(key) ? validate_type(options[key]) : :string
-    end
+module Greenpeace
+  module Configuration
+    # Represents a type entry in a requirement or option. In charge of
+    # validating values and converting them to the appropriate type.
+    class Type
+      TYPES = {
+        string: {
+          converter: :to_s,
+          typeclass: String,
+          regexp: /.*/
+        },
+
+        int: {
+          converter: :to_i,
+          typeclass: Integer,
+          regexp: /^\d+$/
+        }
+      }
+
+      def initialize(options, key)
+        @type = options.key?(key) ? validate_type(options[key]) : :string
+      end
 
-    def valid_value?(value)
-      value.nil? or value.is_a?(type_descriptor[:typeclass])
-    end
+      def valid_value?(value)
+        value.nil? || value.is_a?(type_descriptor[:typeclass])
+      end
+
+      def convert(value)
+        unless value.nil? || value.match(type_descriptor[:regexp])
+          fail "Value #{value} is supposed to be a #{@type}"
+        end
 
-    def convert(value)
-      unless value.match(type_descriptor[:regexp])
-        raise "Value #{value} is supposed to be a #{@type}"
+        value.send(type_descriptor[:converter])
       end
 
-      value.send(type_descriptor[:converter])
-    end
+      def to_s
+        @type.to_s
+      end
 
-    def to_s
-      @type.to_s
-    end
+      private
 
-    private
-    def type_descriptor
-      TYPES[@type]
-    end
+      def type_descriptor
+        TYPES[@type]
+      end
 
-    def validate_type(type)
-      raise "Type cannot be nil" if type.nil?
-      raise "Type must be a symbol" unless type.is_a?(Symbol)
-      unless TYPES.has_key?(type)
-        raise "Type #{type} must be one of #{TYPES.keys.join(", ")}"
+      def validate_type(type)
+        fail 'Type cannot be nil' if type.nil?
+        fail 'Type must be a symbol' unless type.is_a?(Symbol)
+        unless TYPES.key?(type)
+          fail "Type #{type} must be one of #{TYPES.keys.join(', ')}"
+        end
+        type
       end
-      type
     end
   end
 end