envied 0.10.0.alpha1 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 995cd4c0c3790b6eabd16fe27f110ddde99d9efcd52863bc0fdfec9fc7d9ac7f
-  data.tar.gz: 2ae7aebddb419a142c77d2ff3ac878ee22428356ed1d26d1b7b0396741760c14
+  metadata.gz: 0511e3b0eba9370a6b0bd51ef3a3642bbfafa30f12b92a5a007b5ce2293b3c14
+  data.tar.gz: 62100f8640f1b5fc14ac46e8d5a916cf5ba2d3c3f7b14c99a246d06e3482a551
 SHA512:
-  metadata.gz: cc80db096389ad6e7f0d66d615a7697d85a550e10307314ebf98d14cb01172f31a2e29684eb47da2c5693c68e0266fd84cbcc44b1345567e81086fe4ffb690d4
-  data.tar.gz: '08d2dc26b39cc8bd52ed5b40293dff4df06301f645ee5d3d56e52f10c9b6176c9792b2e48a0fc7a0b5358a2805a0a5319555f969ea27913ebcfd02489a10552b'
+  metadata.gz: f92d02db070a5bc4f600ccc360c5d41af97c4766e537d3d29880944b45a7e8d7357d5bf01ea16d9167c1cab44398e14db2e4d7691de9c6e622f6035a322d27dc
+  data.tar.gz: 2ccb1f56a3a626d1177a9a27829e718c344ada5293dd12dd4577d384efd030219adfed807f7f9615f456307c89a7f6f8fe308ea70f2e5d720c6500864b643b8e

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2019 Gert Goet, ThinkCreate
+Copyright (c) 2014 Gert Goet
 
 MIT License
 

data/README.md

@@ -1,36 +1,27 @@
-# ENVied [![pipeline status](https://gitlab.com/envied/envied/badges/master/pipeline.svg)](https://gitlab.com/envied/envied/commits/master) [![project chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://envied-rb.zulipchat.com/)
-
-_Canonical Repository:_ https://gitlab.com/envied/envied/tree/master#envied
+# ENVied [![Tests](https://github.com/javierjulio/envied/actions/workflows/tests.yml/badge.svg)](https://github.com/javierjulio/envied/actions/workflows/tests.yml)
 
 ### TL;DR ensure presence and type of your app's ENV-variables.
 
-For the rationale behind this project, see this [blogpost](https://www.gertgoet.com/2014/10/14/envied-or-how-i-stopped-worrying-about-ruby-s-env.html).
+For the rationale behind this project, see this [blogpost](http://www.gertgoet.com/2014/10/14/envied-or-how-i-stopped-worrying-about-ruby-s-env.html).
 
-## Features
+## Features:
 
 * check for presence and correctness of ENV-variables
 * access to typed ENV-variables (integers, booleans etc. instead of just strings)
 * check the presence and correctness of a Heroku config
 
-## Non-features
-
-* provide or load ENV-values
-
 ## Contents
 
 * [Quickstart](#quickstart)
 * [Installation](#installation)
 * [Configuration](#configuration)
   * [Types](#types)
-  * [Key alias](#key-alias-unreleased)
-    * [env-type](#env-type-unreleased)
   * [Groups](#groups)
+  * [Defaults](#defaults)
+  * [More examples](#more-examples)
 * [Command-line interface](#command-line-interface)
-* [Best Practices](#best-practices)
-* [FAQ](#faq)
-* [Testing](#testing)
+* [How do I...?](#how-do-i)
 * [Development](#development)
-* [Contributing](#contributing)
 
 ## Quickstart
 
@@ -47,13 +38,13 @@ variable :PORT, :integer
 ### 2) Check for presence and coercibility
 
 ```ruby
-# during initialization
+# during initialization and in a pre-deploy confirmation workflow
 ENVied.require
 ```
 
 This will throw an error if:
-* one of `ENV['FORCE_SSL']`, `ENV['PORT']` is absent.
-* or: their values *cannot* be coerced (resp. to boolean and integer).
+* both `ENV['FORCE_SSL']` and `ENV['PORT']` are *not present*.
+* the values *cannot* be coerced to a boolean and integer.
 
 ### 3) Use coerced variables
 
@@ -66,95 +57,66 @@ ENVied.FORCE_SSL # => false
 
 ## Installation
 
-Add this line to your application's Gemfile:
-
-    gem 'envied'
-
-...then bundle:
-
-    $ bundle
-
-...then for Rails applications:
-
-    $ bundle exec envied init:rails
-
-...or for non-Rails applications:
-
-    $ bundle exec envied init
-
-## Configuration
-
-### Types
-
-The following types are supported:
-
-* `:array` (e.g. 'tag1,tag2' becomes `['tag1', 'tag2']`)
-* `:boolean` (e.g. '0'/'1', 'f'/'t', 'false'/'true', 'off'/'on', 'no'/'yes' for resp. false and true)
-* `:date` (e.g. '2014-3-26')
-* `:env` (similar to `:string`, but accessible via ENV - see [Key alias](#key-alias-unreleased) for details)
-* `:float`
-* `:hash` (e.g. 'a=1&b=2' becomes `{'a' => '1', 'b' => '2'}`)
-* `:integer`
-* `:string` (implied)
-* `:symbol`
-* `:time` (e.g. '14:00')
-* `:uri` (e.g. 'http://www.google.com' becomes result of `URI.parse('http://www.google.com')`)
-
-
-### Key alias (unreleased)
+Add `envied` to your `Gemfile`:
 
-By default the value for variable `FOO` should be provided by `ENV['FOO']`. Sometimes though it's convenient to let a different key provide the value, based on some runtime condition. A key-alias will let you do this.  
-
-Consider for example local development where `REDIS_URL` differs between the development and test environment. Normally you'd prepare different shells with different values for `REDIS_URL`: one shell you can run tests in, and other shells where you'd run the console/server etc. This is cumbersome and easy to get wrong.
+```ruby
+gem 'envied'
+```
 
-With a key alias that's calculated at runtime (e.g. `Rails.env`) you'd set values for both `REDIS_URL_TEST` and `REDIS_URL_DEVELOPMENT` and the right value will be used for test and development.
+If you are using Rails, add this to `config/application.rb` immediately after `Bundler.require(*Rails.groups)`:
 
-Full example:
+```ruby
+ENVied.require(*ENV['ENVIED_GROUPS'] || Rails.groups)
 ```
-# file: Envfile
-key_alias! { Rails.env }
 
-variable :REDIS_URL, :uri
-```
+If you are not using Rails, add the following snippet (or similar) to your app's initialization:
 
-Source the following in your environment:
-```
-# file: .envrc
-export REDIS_URL_DEVELOPMENT=redis://localhost:6379/0
-export REDIS_URL_TEST=redis://localhost:6379/1
+```ruby
+ENVied.require(*ENV['ENVIED_GROUPS'] || [:default, ENV['RACK_ENV']])
 ```
-Now commands like `rails console` and `rails test` automatically point to the right redis database.
 
-Note that `ENV['REDIS_URL']` is still considered but `REDIS_URL_<key_alias>` takes precedence.  
-Also: any truthy value provided as key_alias is converted to an upcased string.  
-Finally: this setting is optional.
+Create an `Envfile` with the following as a starter:
 
+```ruby
+enable_defaults! { ENV['RACK_ENV'] != 'production' }
 
-#### env-type (unreleased)
+variable :LOG_LEVEL, :string, default: 'debug'
 
-Variables of type `:env` take the key alias into account when accessing `ENV['FOO']`.
+group :production do
+  variable :SECRET_KEY_BASE
+end
+```
 
-Say, your application uses `ENV['DATABASE_URL']` (wich you can't change to `ENVied.DATABASE_URL`). Normally this would mean that the key alias has no effect. For env-type variables however, the key alias is taken into account:
+Refer to the [Types](#types) section to start configuring your project's environment variables.
 
-```
-# file: Envfile
+### Pre-deploy ENV check
 
-key_alias! { Rails.env }
+To confirm that your ENV variables are set in a pre-deploy workflow, provide the application's current ENV to a Ruby script that loads it and runs the envied check.
 
-variable :DATABASE_URL, :env
+```ruby
+ENV.replace(your_current_env)
+ENVied.require(*RAILS_GROUPS)
+puts "All required ENV variables are present and valid."
 ```
 
-The following now works:
-```shell
-$ DATABASE_URL_DEVELOPMENT=postgres://localhost/blog_development rails runner "p ENV['DATABASE_URL']"
-"postgres://localhost/blog_development"
-```
+If any required ENV are missing, then the check will fail with an error message listing the missing environment variable names.
 
-Note: this also works for `ENV.fetch('FOO')`.  
-Also: no coercion is done (like you would expect when accessing ENV-values directly).  
+## Configuration
 
-This means that for Rails applications when you set values for `DATABASE_URL_DEVELOPMENT` and `DATABASE_URL_TEST`, you no longer need a `config/database.yml`.
+### Types
 
+The following types are supported:
+
+* `:string` (implied)
+* `:boolean` (e.g. '0'/'1', 'f'/'t', 'false'/'true', 'off'/'on', 'no'/'yes' for resp. false and true)
+* `:integer`
+* `:float`
+* `:symbol`
+* `:date` (e.g. '2014-3-26')
+* `:time` (e.g. '14:00')
+* `:hash` (e.g. 'a=1&b=2' becomes `{'a' => '1', 'b' => '2'}`)
+* `:array` (e.g. 'tag1,tag2' becomes `['tag1', 'tag2']`)
+* `:uri` (e.g. 'http://www.google.com' becomes result of `URI.parse('http://www.google.com')`)
 
 ### Groups
 
@@ -163,7 +125,7 @@ It's similar to groups in a Gemfile:
 
 ```ruby
 # file: Envfile
-variable :FORCE_SSL, :boolean
+variable :FORCE_SSL, :boolean, default: 'false'
 
 group :production do
   variable :SECRET_KEY_BASE
@@ -195,6 +157,32 @@ ENVied.require('default')
 ENVied.require(nil)
 ```
 
+### Defaults
+
+In order to let other developers easily bootstrap the application, you can assign defaults to variables.
+Defaults can be a value or a `Proc` (see example below).
+
+Note that 'easily bootstrap' is quite the opposite of 'fail-fast when not all ENV-variables are present'. Therefore you should explicitly state when defaults are allowed:
+
+```ruby
+# Envfile
+enable_defaults! { ENV['RACK_ENV'] == 'development' }
+
+variable :FORCE_SSL, :boolean, default: 'false'
+variable :PORT, :integer, default: proc {|envied| envied.FORCE_SSL ? 443 : 80 }
+```
+
+Please remember that ENVied only **reads** from ENV; it doesn't mutate ENV.
+Don't let setting a default for, say `RAILS_ENV`, give you the impression that `ENV['RAILS_ENV']` is set.
+As a rule of thumb you should only use defaults:
+* for local development
+* for ENV-variables that are solely used by your application (i.e. for `ENV['STAFF_EMAILS']`, not for `ENV['RAILS_ENV']`)
+
+### More examples
+
+* See the [examples](/examples)-folder for a more extensive Envfile
+* See [the Envfile](https://github.com/eval/bunny_drain/blob/c54d7d977afb5e23a92da7a2fd0d39f6a7e29bf1/Envfile) for the bunny_drain application
+
 ## Command-line interface
 
 For help on a specific command, use `envied help <command>`.
@@ -212,55 +200,9 @@ Commands:
   envied version, --version, -v  # Shows version number
 ```
 
-## Best Practices
-
-Some best practices when using ENVied or working with env-configurable applications in general.
-
-### include a .envrc.sample
-
-While ENVied will warn you when you start an application that is 'under-configured', it won't tell users what good default values are. To solve this add a file to the root of your project that contains sane defaults and instructions:
-```
-# file: .envrc.sample
-# copy this file to .envrc and adjust values if needed
-# then do `source .envrc` to load
+## How do I
 
-export DATABASE_URL=postgres://localhost/blog_development
-# export FORCE_SSL=true # only needed for production
-
-# you can find this token on the Heroku-dashboard
-export DEPLOY_TOKEN=1234-ABC-5678
-```
-
-### let [direnv](https://direnv.net/) manage your environment
-
-[direnv](https://direnv.net/) will auto-(un)load values from `.envrc` when you switch folders.  
-
-As a bonus it has some powerful commands in it's [stdlib](https://direnv.net/#man/direnv-stdlib.1).  
-For example:
-```
-# this adds the project's bin-folder to $PATH
-PATH_add bin
-# so instead of `./bin/rails -h` you can do `rails -h` from anywhere (deep) in the project
-
-# the following will use the .envrc.sample as a basis
-# when new variables are introduced upstream, you'll automatically use these defaults
-if [ -f .envrc.sample ]; then
-  source_env .envrc.sample
-fi
-...your overrides
-
-# a variant of this is source_up
-# an .envrc in a subfolder can load the .envrc from the root of the project and override specific values
-# this would allow e.g. for a specific test-environment in the subfolder:
-# in my-project/test/.envrc
-source_up .envrc
-export DATABASE_URL=the-test-db-url
-```
-
-
-## FAQ
-
-### How to find all ENV-variables my app is currently using?
+### ...find all ENV-variables my app is currently using?
 
 ```
 $ bundle exec envied extract
@@ -270,7 +212,7 @@ This comes in handy when you're not using ENVied yet. It will find all `ENV['KEY
 
 It assumes a standard project layout (see the default value for the globs-option).
 
-### How to check the config of a Heroku app?
+### ...check the config of a Heroku app?
 
 The easiest/quickest is to run:
 
@@ -293,44 +235,8 @@ This way you can do stuff like:
 $ ./bin/heroku-env-check && git push live master
 ```
 
-### What happened to default values??
-
-The short version: simplicity, i.e. the best tool for the job.  
-
-In the early days of ENVied it was possible to provide default values for a variable.  
-While convenient, it had several drawbacks:
-- it would introduce a value for ENVied.FOO, while ENV['FOO'] was nil: confusing and a potential source of bugs.
-- it hides the fact that an application can actually be configged via the environment.
-- it creates an in-process environment which is hard to inspect (as opposed to doing `printenv FOO` in a shell, after or before starting the application).
-- there are better ways: e.g. a sample file in a project with a bunch of exports (ie `export FOO=sane-default # and even some documentation`) that someone can source in their shell (see [Best Practices](#best-practices)).
-- made the code quite complex.
-
-As an alternative include a file `.envrc.sample` in the root of your project containing default values (ie `export FOO=bar`) that users can source in their shell. See also [Best Practices](#best-practices).
-
-
 ## Development
 
-```bash
-$ ./bin/setup
-
-# run tests
-$ ./bin/rspec
-
-# hack with pry
-$ ./bin/console
-
-# run CLI:
-$ ./bin/envied
-```
-
-There's a `.envrc.sample` included that can be used in combination with [direnv](http://direnv.net/).
-
-## Contributing
-
-To suggest a new feature, [open an Issue](https://gitlab.com/envied/envied/issues/new) before opening a PR.
-
-1. Fork it: https://gitlab.com/envied/envied/-/forks/new
-2. Create your feature branch: `git checkout -b my-new-feature`
-3. Commit your changes: `git commit -am 'Add some feature'`
-4. Push to the branch: `git push origin my-new-feature`
-5. Create a new pull request for your feature branch
+- `bin/setup`
+- Run tests: `RUBYOPT="-W:deprecated" bundle exec rspec`
+- For an interactive console: `bin/console`

data/lib/envied/cli.rb

@@ -70,9 +70,6 @@ class ENVied
     option :groups, type: :array, desc: "uses ENV['ENVIED_GROUPS'] as default if present", default: ENV['ENVIED_GROUPS'] || %w(default), banner: 'default production'
     option :quiet, type: :boolean, desc: 'Communicate success of the check only via the exit status.'
     def check
-      if rails_project?
-        require File.expand_path 'config/environment.rb'
-      end
       ENVied.require(*options[:groups])
       unless options[:quiet]
         puts "All variables for group(s) #{options[:groups]} are present and valid"
@@ -129,11 +126,5 @@ class ENVied
       template("heroku-env-check.tt", full_dest)
       FileUtils.chmod 0755, full_dest
     end
-
-    no_tasks do
-      def rails_project?
-        File.exists?('config/environment.rb')
-      end
-    end
   end
 end

data/lib/envied/coercer/envied_string.rb

@@ -39,10 +39,6 @@ class ENVied::Coercer::ENViedString
     end
   end
 
-  def to_env(string)
-    to_string(string)
-  end
-
   def to_symbol(str)
     str.to_sym
   end

data/lib/envied/coercer.rb

@@ -22,7 +22,7 @@ class ENVied::Coercer
 
   def self.supported_types
     @supported_types ||= begin
-      [:env, :hash, :array, :time, :date, :symbol, :boolean, :integer, :string, :uri, :float].sort
+      [:hash, :array, :time, :date, :symbol, :boolean, :integer, :string, :uri, :float].sort
     end
   end
 

data/lib/envied/configuration.rb

@@ -1,30 +1,28 @@
 class ENVied
   class Configuration
-    attr_reader :current_group, :coercer
+    attr_reader :current_group, :defaults_enabled, :coercer
 
     def initialize(**options, &block)
       @coercer = options.fetch(:coercer, Coercer.new)
-      @key_alias = options[:key_alias]
+      @defaults_enabled = options.fetch(:enable_defaults, defaults_enabled_default)
       instance_eval(&block) if block_given?
     end
 
-    def key_alias!(value = false, &block)
-      @key_alias = block_given? ? block.call : value
-    end
-
-    def key_alias
-      @key_alias && @key_alias.to_s.upcase
+    def self.load(file='Envfile', **options)
+      envfile = File.expand_path(file)
+      new(**options).tap do |v|
+        v.instance_eval(File.read(envfile), envfile)
+      end
     end
 
-    def enable_defaults!(*args)
-      raise "Defaults are no longer supported. See https://gitlab.com/envied/envied/tree/master#what-happened-to-default-values for the recommended upgrade-path, or pin the gem to 0.9-release (e.g. `gem 'envied', '~> 0.9.2'`) to keep using defaults."
+    def enable_defaults!(value = true, &block)
+      @defaults_enabled = block_given? ? block.call : value
     end
 
-    def self.load(**options)
-      envfile = File.expand_path('Envfile')
-      new(options).tap do |v|
-        v.instance_eval(File.read(envfile), envfile)
-      end
+    def defaults_enabled?
+      @defaults_enabled.respond_to?(:call) ?
+        @defaults_enabled.call :
+        @defaults_enabled
     end
 
     def variable(name, type = :string, **options)
@@ -32,7 +30,7 @@ class ENVied
         raise ArgumentError, "#{type.inspect} is not a supported type. Should be one of #{coercer.supported_types}"
       end
       options[:group] = current_group if current_group
-      variables << ENVied::Variable.new(name, type, options)
+      variables << ENVied::Variable.new(name, type, **options)
     end
 
     def group(*names, &block)
@@ -47,5 +45,15 @@ class ENVied
     def variables
       @variables ||= []
     end
+
+    private
+
+    def defaults_enabled_default
+      if ENV['ENVIED_ENABLE_DEFAULTS'].nil?
+        false
+      else
+        @coercer.coerce(ENV['ENVIED_ENABLE_DEFAULTS'], :boolean)
+      end
+    end
   end
 end

data/lib/envied/env_proxy.rb

@@ -28,6 +28,7 @@ class ENVied
 
     def value_to_coerce(var)
       return env_value_of(var) unless env_value_of(var).nil?
+      config.defaults_enabled? ? default_value_of(var) : nil
     end
 
     private
@@ -46,16 +47,12 @@ class ENVied
       coercer.coercible?(value_to_coerce(var), var.type)
     end
 
-    def env_value_of(var)
-      ENV.values_at(*env_keys(var, key_alias: config.key_alias)).compact.first
+    def default_value_of(var)
+      var.default_value(ENVied, var)
     end
 
-    def env_keys(var, key_alias: nil)
-      base_key = var.name.to_s
-
-      result = [base_key]
-      result.unshift "#{base_key}_#{key_alias}" if key_alias
-      result
+    def env_value_of(var)
+      ENV[var.name.to_s]
     end
 
     def missing?(var)

data/lib/envied/variable.rb

@@ -1,14 +1,23 @@
 class ENVied::Variable
-  attr_reader :name, :type, :group
+  attr_reader :name, :type, :group, :default
 
   def initialize(name, type, **options)
     @name = name.to_sym
     @type = type.to_sym
     @group = options.fetch(:group, :default).to_sym
+    @default = options[:default]
+
+    #if !@default.is_a? String
+    #  raise ArgumentError, "Default values should be strings (variable #{@name})"
+    #end
+  end
+
+  def default_value(*args)
+    default.respond_to?(:call) ? default[*args] : default
   end
 
   def ==(other)
     self.class == other.class &&
-      [name, type, group] == [other.name, other.type, other.group]
+      [name, type, group, default] == [other.name, other.type, other.group, other.default]
   end
 end

data/lib/envied/version.rb

@@ -1,3 +1,3 @@
 class ENVied
-  VERSION = '0.10.0.alpha1'
+  VERSION = '0.10.0'
 end

data/lib/envied.rb

@@ -5,7 +5,6 @@ require 'envied/coercer'
 require 'envied/coercer/envied_string'
 require 'envied/variable'
 require 'envied/configuration'
-require 'envied/env_interceptor'
 
 class ENVied
   class << self
@@ -15,11 +14,10 @@ class ENVied
 
   def self.require(*args, **options)
     requested_groups = (args && !args.empty?) ? args : ENV['ENVIED_GROUPS']
-    env!(requested_groups, options)
-    error_on_missing_variables!(options)
-    error_on_uncoercible_variables!(options)
+    env!(requested_groups, **options)
+    error_on_missing_variables!(**options)
+    error_on_uncoercible_variables!(**options)
 
-    intercept_env_vars!
     ensure_spring_after_fork_require(args, options)
   end
 
@@ -54,23 +52,9 @@ class ENVied
     result.any? ? result.map(&:to_sym) : [:default]
   end
 
-  def self.env_keys_to_intercept
-    config.variables.select {|var| var.type == :env }.map{|var| var.name.to_s }
-  end
-
-  def self.intercept_env_vars!
-    if (keys = env_keys_to_intercept).any?
-      ENV.instance_eval { @__envied_env_keys = keys }
-      class << ENV
-        prepend(ENVied::EnvInterceptor)
-      end
-    end
-  end
-  private_class_method :intercept_env_vars!, :env_keys_to_intercept
-
-  def self.ensure_spring_after_fork_require(args, **options)
+  def self.ensure_spring_after_fork_require(args, options)
     if spring_enabled? && !options[:via_spring]
-      Spring.after_fork { ENVied.require(args, options.merge(via_spring: true)) }
+      Spring.after_fork { ENVied.require(*args, **options.merge(via_spring: true)) }
     end
   end
 
@@ -99,5 +83,4 @@ class ENVied
   def self.respond_to_missing?(method, include_private = false)
     (env && env.has_key?(method)) || super
   end
-
 end