settei 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 420fd42e68113f4e584bd112c0fcf0614d5f9622
-  data.tar.gz: e3fb141eca64df590927a41d97ce581832ec697f
+  metadata.gz: ea3ce2375e85ac9e98985d0ec6ae3876f0698fd9
+  data.tar.gz: 534303064fc333645a928ebb3fcde9272a82289f
 SHA512:
-  metadata.gz: '083334231d67b72fbfb8fada4b0212e58d709bf4b94ff8c679e09342d9a96fbc83fc38378edebcc7a61d928f6c632ac22df0b7e0d571c7f25c2846810629dc1b'
-  data.tar.gz: '058da9d1f4ef97479c449d9a6edcec8ac6a31c9e52f129da5601290a6b9e7861d0b2f0b59ab05c636c4fe12089ca9f9123d621fc2c2a5e61033c7431574e1c14'
+  metadata.gz: 65ac49d58685f659586bf9f4fead8b5f99efdd217f7691fbcad2b6dbb7f5338da211553eae50e599c39bb481129894269ba3acf1d29dec38f96f280e5efd42ae
+  data.tar.gz: d1720aac8d9f8ced2326cc36917ebda0cd912d79bc8aad4d38f406c766032319be613f5108a981ce5b74815cc7b62e06f139935007a0e780faf034dbe56bdcde

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    settei (0.1.1)
+    settei (0.1.2)
 
 GEM
   remote: https://rubygems.org/

data/LICENSE.txt

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 lulalala (mark@goodlife.tw)
+
+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/README.md

@@ -1,13 +1,18 @@
 # Settei
 
-Hash based configuration with flexibility and 12-factor app deployment in mind
+Config as YAML file yet still being 12-factor compliant...
 
-## Design Philosophies
+...by serializing the file as one environment variable.
+
+![Settei Illustrated](misc/illustrated.png?raw=true "Settei Illustrated")
+
+## Features
+
+* Can be read without loading Rails
+* Variable namespacing using nested hash
+* Follows 12-factor [rule 3](https://12factor.net/config) - store config in the environment
+* Customizable due to loosely coupled PORO parts
 
-* Fast as it is accessible without loading Rails
-* Ease of management as nested hash is allowed
-* 12-factor compatible by serializing as environment variable.
-* Minimal meta-programming magics, so you can add your flavor of magic.
 
 ## Installation
 
@@ -21,56 +26,151 @@ And then execute:
 
     $ bundle
 
-Or install it yourself as:
+For Rails, execute this rake task for out-of-the-box setup:
 
-    $ gem install settei
+    $ rake settei:install:rails
+
+This task does the following things:
+
+* create `config/setting.rb` for setting up `Setting`.
+* require the above in `config/application.rb`
+* create YAML files `config/environments/default.yml` and `config/environments/production.yml`
+* make git ignore YAML files above
+* append script to `deploy.rb` so config is passed via env var to production
 
 ## Usage
 
-For Rails, a rake task is available for simple setup:
+If `config/environments/default.yml` contains the following:
 
-    $ rake settei:install:rails
+```yaml
+the_answer_to_life_the_universe_and_everything: 42
+google:
+  api: foo
+```
+
+Then you can access those like this:
+
+```ruby
+Setting.dig(:the_answer_to_life_the_universe_and_everything)
+Setting.dig(:google, :api)
+```
+
+`#dig` is used to access its values. It's convenient because it does not err if nested hash is absent.
+
+`#dig_and_wrap` will return a `Settei::Base` if it the return value is a hash.
+
+For other available methods, [check here](http://www.rubydoc.info/github/lulalala/settei/master/Settei/Base).
+
+If you have `development.yml` or `test.yml`, it will be loaded instead of `default.yml`.
+
+### Deploy
+
+If you use Capistrano or Mina, the `deploy.rb` is modified so deploy process will serialize `production.yml` into one long string, and pass it to remote server as **a single environment variable**. There it is de-serialized and loaded, and the rest works the same way.
+
+If you use Heroku, use `rake settei:heroku:config:set app=[app_name]` to upload your config. You need heroku-cli and authenticate first.
+
+## Why
+
+Most config gems have not been updated for ages, and do not meet my needs:
+
+I want to be 12-factor compliant, but I also hate using environment variables. See the following example: naming is hard and names tend to be very long. Passing more env vars also becomes more impractical.
+
+```
+BOARD_PAGINATION_PER_PAGE=5
+BOARD_PAGINATION_MAX_PAGE=10
+BOARD_REPLY_OMIT_CONDITION_N_RECENT_ONLY=5
+BOARD_REPLY_OMIT_CONDITION_AVOID_ONLY_N_HIDDEN=2
+```
 
-A `config/setting.rb` file is added for basic setup.
- 
-YAML files are added under `config/environments` and is ignored by git.
+In comparison YAML allows nested hash, so we can manage them using namespaces.
 
-In your app, you can access the settings like this:
+```yaml
+board:
+  pagination:
+    per_page: 5
+    max_page: 10
+  reply_omit_condition:
+    n_recent_only: 5
+    avoid_only_n_hidden: 2
+```
+
+Can I have the benefit of env var (12-factor) and benefit of YAML (ease of variable mangement) at the same time?
+
+Yes, if settings are stored in YAML files, but during deploy, transfer the whole YAML **file** as one env var.
+
+I feel it is simpler and more effective.
+
+## Tips
+
+Rails `secrets.yml` and `credentials.yml.enc` are needlessly complex, and now we are able to ignore them:
+
+Do away with Rails 4.1 secret.yml with something like this:
+```ruby
+# secret_token.rb
+Foo::Application.config.secret_token = Setting.dig(:rails, :secret_token)
+Foo::Application.config.secret_key_base = Setting.dig(:rails, :secret_key_base)
+```
+
+Similarly with Rails 5.2's credentials:
 
 ```ruby
-Setting.dig(:google, :api, :secret)
+# application.rb
+config.secret_token = Setting.dig(:rails, :secret_token) 
+config.secret_key_base = Setting.dig(:rails, :secret_key_base) 
 ```
 
-### Settei::Base 
+Maybe we can get rid of `database.yml` one day too.
 
-`Settei::Base` is the core class for accessing the configurations. It is initialized by a hash. It is a light wrapper intended for you to extend.
+## Customization
 
-`#dig` is used to access its values. It's convenient because it does not err if nested hash is absent.
+The default setup is probably good enough for 90% of the users. However if you have advance requirements, you can easily customize.
 
-`#dig_and_wrap` will return a `Settei::Base` if it the return value is a hash.
+One can start by editing the generated `setting.rb` file. The three parts are `Settei::Base`, loader and deploy script:
+
+### Settei::Base
+
+`Setting` is an instance of `Settei::Base`, the accessor of the configurations. It is initialized by a hash.
 
-For other methods, [check here](http://www.rubydoc.info/github/lulalala/settei/master/Settei/Base).
+You can change `Setting` to other constants or a global variable.
 
-Install script maps `Setting` to an instance of `Settei::Base`, for convenience.
+You can also extend or replace `Settei::Base` with your own class, or you can just use the hash without any wrapper.
+
+**Note** For Ruby < 2.3, `Hash#dig` is not available. What you can do is to replace `Settei::Base` with your own class, or even use `SettingsLogic.new(hash)`.
 
 ### Loader
 
-`Settei::Loaders::SimpleLoader` is responsible for providing the hash to initialize `Settei::Base`. It loads from a source such as YAML or environment variable. It can also serialize the whole hash into one string, suitable for deploying via environment variables.
+Loaders are responsible for returning the configuration as hash, used to initialize `Settei::Base`.
+
+`Settei::Loaders::SimpleLoader` is one type of loader. It loads from YAML or environment variable. 
+
+When initializing it, you can set:
+
+* `dir`: the full path to directory containing YAML files
+* `env_name`: the environment variable name; defaults to APP_CONFIG
 
 ```ruby
 loader = Settei::Loaders::SimpleLoader.new(dir: 'path/to/dir')
+```
+
+To load data, call `load(Rails.env)`. In development environment, it tries to load `development.yml` if it exists, else it loads `default.yml`.
+
+Once data is loaded, we can obtain it in hash form by calling `as_hash`
+
+The deploy script also relies on loader's ability to serialize the whole hash into one string, suitable for deploying as environment variable. The methods `as_env_assignment` and `as_env_value` are provided for this purpose, e.g.:
+
+```ruby
 loader.load.as_hash # loads default.yml and returns a hash
 loader.load(:production).as_env_value # loads production.yml and returns "XYZ"
 loader.load(:test).as_env_assignment # loads test.yml and returns "APP_CONG=XYZ"
 ```
 
-We welcome PRs for different types of loaders, as `SimpleLoader` probably can't handle all situations.
+But no one is stopping you from writing your own loader. For example you might want the loader to encrypt/decrypt ENV value, or you may want to load from .env file.
 
-For other methods, [check here](http://www.rubydoc.info/github/lulalala/settei/master/Settei/Loaders/SimpleLoader).
+For more detailed doc of `SimpleLoader`, [check here](http://www.rubydoc.info/github/lulalala/settei/master/Settei/Loaders/SimpleLoader).
 
-### Deployment
+### Deploy script
 
-If `deploy.rb` is present, `rake settei:install:rails` will append code to it, allow serialized config to be passed as an environment variable.
+If you have more complex deploy requirements, just edit/revert the changes on `deploy.rb`.
 
 ### Frameworks other than Rails
 
@@ -79,23 +179,22 @@ Settei is designed to be simple so you can integrate it into any frameworks easi
 1. Designate a folder for storing YAML files.
 2. Create a `setting.rb` file, in which `Settei::Base` is initialized (see `templates/setting.rb`)
 3. Require it when framework starts.
-4. Load and pass serialized production config as environment variable in deploy script (see `templates/_capistrano.rb` or `templates/_mina.rb`).
-
-We also welcome PRs for generators of other frameworks too.
-
-## Ruby < 2.3
-
-`Settei::Base` uses `dig` to access the configuration, available since Ruby 2.3. If your Ruby is not new enough, don't be afraid. Write your own hash accessor literally takes minutes. You can even use `SettingsLogic.new(hash)` .
+4. Load production.yml, pass its serialized form as environment variable to production (see `templates/_capistrano.rb` or `templates/_mina.rb`).
 
 ## FAQ
 
 **Q:** Would serialized configuration be too big for environment variable?  
 **A:** [The upper limit is pretty big.](https://stackoverflow.com/a/1078125/474597)
 
+## Contribution
 
-## TODO
+The slogan "YAML config yet still 12-factor compliant" is not entirely correct. Why not load from TOML or .env? If there is a need we can accommodate for that.
 
-* Integrate Rails configurations (e.g. database) into Settei.
-* Explore deep merge hash so development.yml can combine with default.yml.
-* Make loader configurable so it is easy to add and mix functionality.
+PRs are welcomed. Some ideas are:
 
+* generators for other frameworks
+* loader or its plugins
+* plugin for `Settei::Base`
+* explore deep merge hash so development.yml can combine with default.yml.
+* make loader configurable so it is easy to add and mix functionality.
+* rake task for heroku setup

data/lib/settei.rb

@@ -1,4 +1,4 @@
 require_relative "settei/version"
 require_relative "settei/base"
 require_relative "settei/loaders/simple_loader"
-require_relative 'settei/railtie' if !!defined?(Rails)
+require_relative 'settei/railtie' if defined?(Rails)

data/lib/settei/version.rb

@@ -1,3 +1,3 @@
 module Settei
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/tasks/settei_tasks.rake

@@ -1,11 +1,27 @@
 require 'rake'
-require 'settei/generators/rails'
 
 namespace :settei do
   namespace :install do
     desc "Setup settei for Rails project"
     task :rails do
+      require 'settei/generators/rails'
       Settei::Generators::Rails.new(app_path: Dir.pwd).run
     end
   end
+
+  namespace :heroku do
+    namespace :config do
+      desc "Update environment variable on Heroku"
+      task :set do
+        require 'settei/loaders/simple_loader'
+        dir = File.join(Dir.pwd, 'config', 'environments')
+        loader = Settei::Loaders::SimpleLoader.new(dir: dir)
+        loader.load(:production)
+
+        sh %{
+          heroku config:set #{loader.as_env_assignment} --app #{ENV['app']}
+        }
+      end
+    end
+  end
 end

data/settei.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["lulalala"]
   spec.email         = ["mark@goodlife.tw"]
 
-  spec.summary       = %q{Hash based configuration}
-  spec.description   = %q{Hash based configuration with flexibility and 12-factor app deployment in mind. Settei allows use of nested hash, and can be serialized as environment variable, suitable for 12-factor app.}
+  spec.summary       = %q{Config as YAML yet still 12-factor compliant}
+  spec.description   = %q{Config as YAML yet still being 12-factor compliant, by serializing the file as one environment variable.}
   spec.homepage      = "https://github.com/lulalala/settei"
   spec.licenses      = ['MIT']
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: settei
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - lulalala
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-03-06 00:00:00.000000000 Z
+date: 2018-03-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,9 +66,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Hash based configuration with flexibility and 12-factor app deployment
-  in mind. Settei allows use of nested hash, and can be serialized as environment
-  variable, suitable for 12-factor app.
+description: Config as YAML yet still being 12-factor compliant, by serializing the
+  file as one environment variable.
 email:
 - mark@goodlife.tw
 executables: []
@@ -80,6 +79,7 @@ files:
 - ".yardopts"
 - Gemfile
 - Gemfile.lock
+- LICENSE.txt
 - README.md
 - Rakefile
 - bin/console
@@ -92,6 +92,7 @@ files:
 - lib/settei/railtie.rb
 - lib/settei/version.rb
 - lib/tasks/settei_tasks.rake
+- misc/illustrated.png
 - settei.gemspec
 - templates/_capistrano.rb
 - templates/_mina.rb
@@ -120,5 +121,5 @@ rubyforge_project:
 rubygems_version: 2.6.13
 signing_key: 
 specification_version: 4
-summary: Hash based configuration
+summary: Config as YAML yet still 12-factor compliant
 test_files: []