easy_conf 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6867474022805747ef2c360053e00d7c97f5f66d
-  data.tar.gz: 7a9321beeba8722dc7c82830233b4284150fe381
+  metadata.gz: 78e252ae88731a6e0a71c05b14871714c50ba738
+  data.tar.gz: bce63f90b3310f312153995eb0441b17b009d21d
 SHA512:
-  metadata.gz: f6c4e451cc84947a46764a841c50c841b1209650c0c159cb493e38bbfc5971b44560b32b9d14555ce91acf66d94d3cd04e687ca6adca85f960c2edbc712c639f
-  data.tar.gz: 9c8131e7cb77f41d0cc55ab78b6bfd01f82975dd34073de91e561ab4ff55b64aefa6b454b9f0b96f5d79eb5c74563af54ae2e9b20dabf261d760a54d4ee1d3ba
+  metadata.gz: a53045c54df06d04bc67731d58b959f2ec6d6b062a1622d1734f02d568421543d0644de8a160ad20f4bd9c618a76875dc25f64be987d8e99e704e48cbd8cd98b
+  data.tar.gz: 2466eeae91287e081ec582eba490a5767f9e7e6d879f4eec65ea3d660ff655bbf88e21fc95388ab74c38d4a1afbb6ed14dc0af65d882227efe76b4a583ef61fa

data/.gitignore

@@ -7,3 +7,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+*.gem

data/README.md

@@ -1,8 +1,12 @@
 # EasyConf
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/easy_conf`. To experiment with that code, run `bin/console` for an interactive prompt.
+EasyConf, as its name suggest, is a gem for managing application configuration easily. It works really simple; tries to get configuration key from config files you've specified and uses environment variables as fallback. So if configuration key is not found on config files it will look at the environment variables.
 
-TODO: Delete this and the text above, and describe your gem
+You may wonder why I've created this gem. The answer is simple; because convention matters!
+
+I saw lots of applications written buy other awesome developers and I noticed that they are managing their configurations either by using config files or environment variables or even both! As a result of this, in this applications you can see something like  `ENV['foo']` and `Rails.application.config` mixed all around the source of the application. What a mess.
+
+Beside of this complexity your production environment may have some restrictions you don't have on your own development environment. For example, if you are using Heroku you can't use config files to configure your application. Because you have to untrack config files on your VCS unless you have a good reason to track them. By using EasyConf while you can configure your application with config files also you can use environment variables on your production environment and this will give you a good abstraction on configuration!
 
 ## Installation
 
@@ -22,20 +26,128 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+#### EasyConf configuration
+
+EasyConf requires its own configuration to determine where is configuration files. For Rails applications, create a file under config directory which looks like;
+
+```ruby
+require 'easy_conf'
+
+EasyConf.configure do |config|
+  config.config_files    = ["#{Rails.root}/config/config.yml"]
+  config.inform_with     = :log
+  config.white_list_keys = [:foo]
+  config.environment     = :production
+end
+```
+
+For other ruby applications, place this file wherever you want and load it at the top of the application.
+
+#### Accessing configuration keys
+
+After configuration you can use it inside of your code like this;
+
+```ruby
+EasyConf.get(:redis_url) # tries to load redis_url from yml or environment variable
+EasyConf.read(:redis_url) # alias of get method
+EasyConf.app_config.redis_url # another alias for accessing configuration keys
+```
+
+You may want to define a global variable or a constant on top level of your application like `easy_conf.rb` configuration file to get keys as method calls.
+
+By constants;
+
+```ruby
+CONFIG = EasyConf.app_config # define this constant on top level of your application
+```
+
+By global variables;
+
+```ruby
+$config = EasyConf.app_config
+```
+
+You can get all configuration keys as an array like;
+
+```ruby
+EasyConf.keys # [:foo, ...]
+```
+Or if you want to get your configurations from config files as Hash, you can just do;
+
+```ruby
+EasyConf.to_hash # { "foo" => "bar" }
+```
 
-## Development
+## Configuration Keys
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+**config_files:** *Required! List of configuration files to be used.
+If you don't configure this, EasyConf can read configurations from only environment variables.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+**inform_with:** Optional. Information method used in case of error. Whether sliently puts log or raises exception. Valid options are `:log` and `:exception`. Default is `:log`.
+
+**white_list_keys:** Optional. List of config keys to be used. If this configuration is set, config keys which are not in this list won't be accessible through EasyConf!
+
+**black_list_keys:** Optional. List of config keys to be ignored. If this configuration is set, config keys which are in this list won't be accessible through EasyConf! *Note that, black list keys overrides white list keys.*
+
+**environment:** Optional. Specifies environment scope. For Rails applications, the value is same with Rails.
+
+## TIPS
+
+#### Configuring Rails Initializers With EasyConf
+
+If you want to use EasyConf to configure your Rails initializers, put EasyConf configuration file to root of your Rails project and require EasyConf file in your `config/application.rb` file. But keep that in your mind, if you require EasyConf on top of your initializer you can't use `Rails.root` while configuring EasyConf anymore. In this case you have to give absolute paths by yourself.
+
+```ruby
+...
+Bundler.require(*Rails.groups)
+
+require File.expand_path('../easy_conf', __FILE__)
+
+module YourApp
+  class Application < Rails::Application
+...
+```
+
+Then configure EasyConf like;
+
+
+```ruby
+require 'easy_conf'
+
+EasyConf.configure do |config|
+  config.config_files    = ["/Users/.../config/config.yml"]
+end
+```
+
+#### Deploy With AWS Elastic Beanstalk
+
+AWS Elastic Beanstalk is a really good service to deploy applications into AWS. With Elastic Beanstalk you can use a command line interface to deploy your application in minutes. But because lack of information you may struggle to configure your application. The easiest way to configure your application is using environment variables. To set environment variables you can use either AWS Console or AWS CLI. However if you have lots of configurations AWS has a bad news for you! There is a limitation on environment variables. You can use only *4096* characters to set environment variables for your application. If you reach the limitations you may want to use configuration files to configure your application. But remember that we have to untrack our configuration files. The solution is simple; use `ebextensions` to place your config files into your application directory during deployment. Here is a sample extension which reads configuration file from private S3 bucket and writes it into the correct location.
+
+```
+files:
+  "/opt/elasticbeanstalk/hooks/appdeploy/pre/01a_get_config_yml.sh":
+    mode: "000777"
+    content: |
+      . /opt/elasticbeanstalk/support/envvars
+
+      cd /var/app/ondeck/config
+      aws s3 cp $remote_config_file config.yml
+```
+
+This little shell script reads the location of config file from environment file, downloads it and writes it into the place where it should be. You have to adjust access policies for your S3 and Elastic Beanstalk user otherwise it can't download the configuration file.
+
+If you think storing configuration files at S3 is not good then you can use some tools like Apache ZooKeeper. For now EasyConf doesn't support it but you can find it in TODO list.
+
+## TODO
+
+1. Write tests
+2. Write adapter for ZooKeeper
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/easy_conf.
+Bug reports and pull requests are welcome on GitHub at https://github.com/meinac/easy_conf.
 
 
 ## License
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
-

data/lib/easy_conf/app_config.rb

@@ -0,0 +1,84 @@
+module EasyConf
+  class AppConfig # :nodoc
+
+    MESSAGES = {
+      unpermitted_key:  'Found unpermitted key'.freeze,
+      file_not_found:   'Configuration file not found'.freeze,
+      config_not_found: 'Configuration not found'.freeze,
+    }
+
+    EXCEPTIONS = {
+      unpermitted_key:  'UnpermittedConfigError'.freeze,
+      file_not_found:   'ConfigFileNotFoundError'.freeze,
+      config_not_found: 'ConfigNotFoundError'.freeze,
+    }
+
+    def initialize
+      @table = __read_config
+    end
+
+    def method_missing(meth, *args, &block)
+      return __notify(:unpermitted_key, meth) if __list_check(meth)
+
+      __read_from_table(meth) || __read_from_env(meth) || __notify(:config_not_found, meth)
+    end
+
+    def __keys
+      @table.keys
+    end
+
+    def __to_hash
+      @table.dup
+    end
+
+    private
+      def __configuration
+        EasyConf.configuration
+      end
+
+      def __read_config
+        env = __configuration.environment.to_s
+
+        __configuration.config_files.inject({}) do |conf, config_file|
+          tmp = if File.exists?(config_file)
+            yaml_data = YAML.load_file(config_file)
+            env.blank? ? yaml_data : yaml_data.fetch(env, {})
+          else
+            __notify(:file_not_found, config_file) && {}
+          end
+          conf.merge(tmp)
+        end
+      end
+
+      def __read_from_table(key)
+        if val = @table[key.to_s]
+          define_singleton_method(key) { val }
+          send(key)
+        end
+      end
+
+      def __read_from_env(key)
+        if val = ENV[key.to_s]
+          define_singleton_method(key) { val }
+          send(key)
+        end
+      end
+
+      def __list_check(key)
+        (__configuration.black_list_keys.length > 0 && __configuration.black_list_keys.include?(key)) ||
+          (__configuration.black_list_keys.length == 0 &&
+            (__configuration.white_list_keys.length > 0 && !__configuration.white_list_keys.include?(key)))
+      end
+
+      def __notify(event, obj)
+        message = "#{MESSAGES[event]}: `#{obj}`"
+
+        if __configuration.inform_with == :exception
+          exception_class = "EasyConf::#{EXCEPTIONS[event]}"
+          raise exception_class.constantize.new(message)
+        else
+          puts message
+        end
+      end
+  end
+end

data/lib/easy_conf/configuration.rb

@@ -0,0 +1,24 @@
+module EasyConf
+  class Configuration # :nodoc
+    attr_accessor :config_files, :inform_with, :white_list_keys, :black_list_keys, :environment
+
+    def initialize
+      @config_files    = []
+      @inform_with     = :log
+      @white_list_keys = []
+      @black_list_keys = []
+    end
+
+    def white_list_keys=(keys)
+      @white_list_keys = keys.map(&:to_sym)
+    end
+
+    def black_list_keys=(keys)
+      @black_list_keys = keys.map(&:to_sym)
+    end
+
+    def environment
+      @environment ||= defined?(Rails) ? Rails.env : nil
+    end
+  end
+end

data/lib/easy_conf/errors/config_file_not_found_error.rb

@@ -0,0 +1,9 @@
+module EasyConf
+  class ConfigFileNotFoundError < IOError
+
+    def backtrace
+      []
+    end
+
+  end
+end

data/lib/easy_conf/errors/config_not_found_error.rb

@@ -0,0 +1,4 @@
+module EasyConf
+  class ConfigNotFoundError < IOError
+  end
+end

data/lib/easy_conf/errors/unpermitted_config_error.rb

@@ -0,0 +1,4 @@
+module EasyConf
+  class UnpermittedConfigError < ArgumentError
+  end
+end

data/lib/easy_conf/version.rb

@@ -1,3 +1,3 @@
 module EasyConf
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/easy_conf.rb

@@ -1,5 +1,88 @@
 require "easy_conf/version"
+require "easy_conf/app_config"
+require "easy_conf/configuration"
+require "easy_conf/errors/config_not_found_error"
+require "easy_conf/errors/unpermitted_config_error"
+require "easy_conf/errors/config_file_not_found_error"
 
 module EasyConf
-  
+
+  class << self
+    # Returns all configurations of your applications.
+    #
+    # Example:
+    #
+    #   EasyConf.app_config # => <EasyConf::AppConfig>
+    #
+    # You can access configurations of your application by
+    # method call with configuration name.
+    #
+    # Example:
+    #
+    #   EasyConf.app_config.access_key # => "some_key"
+    def app_config
+      @config ||= AppConfig.new
+    end
+
+    # Read Application configuration by sending key as argument.
+    #
+    # Example:
+    #
+    #   EasyConf.read(:access_key) # => "some_key"
+    def read(key)
+      app_config.send(key.to_s)
+    end
+    alias_method :get, :read
+
+    # Read Application config keys
+    #
+    # Example:
+    #
+    #   EasyConf.keys # => [:foo, :bar, ...]
+    def keys
+      app_config.__keys
+    end
+
+    # Get application configs as Hash
+    #
+    # Example:
+    #
+    #   EasyConf.to_hash # => { foo: 'bar', ... }
+    def to_hash
+      app_config.__to_hash
+    end
+
+    # Configures the EasyConf gem for the following keys;
+    #
+    # config_files    : Required! List of configuration files to be used.
+    # inform_with     : Optional. Information method used in case of error.
+    #                   Whether sliently puts log or raises exception.
+    # white_list_keys : Optional. List of config keys to be used.
+    #                   If this configuration is set, config keys
+    #                   which are not in this list won't be
+    #                   accessible through EasyConf!
+    # black_list_keys : Optional! List of config keys to be ignored.
+    #                   If this configuration is set, config keys
+    #                   which are in this list won't be accessible
+    #                   through EasyConf!
+    # environment     : Optional. Specifies environment scope. For Rails
+    #                   applications, the value is same with Rails.
+    #
+    # Example:
+    #
+    #   EasyConf.configure do |config|
+    #     config.config_files    = [config.yml]
+    #     config.white_list_keys = ['access_key', 'secret_key', ...]
+    #     config.black_list_keys = ['black_key', ...]
+    #   end
+    def configure
+      yield(configuration)
+      app_config # initialize config
+    end
+
+    def configuration # :nodoc
+      @configuration ||= Configuration.new
+    end
+  end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: easy_conf
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Mehmet Emin İNAÇ
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-08 00:00:00.000000000 Z
+date: 2016-02-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -72,6 +72,11 @@ files:
 - bin/setup
 - easy_conf.gemspec
 - lib/easy_conf.rb
+- lib/easy_conf/app_config.rb
+- lib/easy_conf/configuration.rb
+- lib/easy_conf/errors/config_file_not_found_error.rb
+- lib/easy_conf/errors/config_not_found_error.rb
+- lib/easy_conf/errors/unpermitted_config_error.rb
 - lib/easy_conf/version.rb
 homepage: http://github.com/meinac/easy_conf
 licenses: