envied 0.9.3 → 0.10.0.alpha1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcc781ac6f01f4925045b61ca88d14b41dbccebe46dc34582a391c884bb99e4a
-  data.tar.gz: 542a7c711445013a845478f716cddf7ac82b7834365429ebf24ed36b08462ca2
+  metadata.gz: 995cd4c0c3790b6eabd16fe27f110ddde99d9efcd52863bc0fdfec9fc7d9ac7f
+  data.tar.gz: 2ae7aebddb419a142c77d2ff3ac878ee22428356ed1d26d1b7b0396741760c14
 SHA512:
-  metadata.gz: 2c976e128a2c3c8ab59c31fbec653aa7fe3b8d01973e92e4da220deff09cdee826c34627ca873d4eb612292f175419914c4235932002422cab3454f72b3da2d8
-  data.tar.gz: f37e48c5f981902d2db3e46dfa2a6101998ef11987e48e59ac9fc8e951d5b48d4e1cc6da756ff9b1860bb01e2abf6c72d0f1563a453f3e412754c2f0b8cfcbbb
+  metadata.gz: cc80db096389ad6e7f0d66d615a7697d85a550e10307314ebf98d14cb01172f31a2e29684eb47da2c5693c68e0266fd84cbcc44b1345567e81086fe4ffb690d4
+  data.tar.gz: '08d2dc26b39cc8bd52ed5b40293dff4df06301f645ee5d3d56e52f10c9b6176c9792b2e48a0fc7a0b5358a2805a0a5319555f969ea27913ebcfd02489a10552b'

data/.envrc.sample

@@ -0,0 +1,9 @@
+# Copy this file to .envrc, adjust values if needed and
+# `source .envrc` to apply it.
+# Or use [direnv](https://direnv.net/) to auto-(un)load it.
+
+# using direnv
+# PATH_add bin
+
+# without direnv
+# export PATH="$(pwd)/bin:${PATH}"

data/.github/pull_request_template.md

@@ -0,0 +1,2 @@
+*NOTE* the canonical repository for this project can be found at **https://gitlab.com/envied/envied**.  
+Please open issues and send patches there.

data/.gitignore

@@ -12,3 +12,4 @@
 .rspec_status
 
 Gemfile.lock
+.envrc

data/.gitlab-ci.yml

@@ -8,7 +8,7 @@
     - 'git -v || apk --update add git'
     - bundle install -j $(nproc)
   script:
-    - bundle exec rake
+    - ./bin/rspec
 
 rspec ruby-2.4:
   image: ruby:2.4-alpine
@@ -30,7 +30,7 @@ rspec jruby-9.2:
   image: jruby:9.2-alpine
   <<: *rspec
   only:
-    - 0-9-releases
+    - master
 
 release:
   stage: deploy
@@ -46,4 +46,5 @@ release:
     - chmod 600 ~/.gem/credentials
     - bundle exec rake release
   only:
-    - tags
+    - tags
+  environment: production

data/.rspec

@@ -1,2 +1,3 @@
 --color
 --require spec_helper
+--format documentation

data/CHANGELOG.md

@@ -1,4 +1,16 @@
-## 0.9.2 / 2019-06-29
+## master / unreleased
+
+### Added
+
+* key alias
+
+        # file: Envfile
+        key_alias! { Rails.env }
+        variable :FOO
+
+        The value of ENV['FOO_DEVELOPMENT'] will take precedence over ENV['FOO'] when running in development.
+
+## 0.9.3 / 2019-06-29
 
 * Project moved to GitLab (https://gitlab.com/envied/envied)
 * Now requiring Ruby 2.4+ [#48], [#51]

data/LICENSE.txt

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

data/README.md

@@ -1,28 +1,35 @@
-# ENVied [![pipeline status](https://gitlab.com/envied/envied/badges/0-9-releases/pipeline.svg)](https://gitlab.com/envied/envied/commits/0-9-releases) [![project chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://envied-rb.zulipchat.com/)
+# 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
 
 ### TL;DR ensure presence and type of your app's ENV-variables.
 
-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).
+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).
 
-## 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)
-* [How do I...?](#how-do-i)
+* [Best Practices](#best-practices)
+* [FAQ](#faq)
 * [Testing](#testing)
-* [Developing](#developing)
+* [Development](#development)
 * [Contributing](#contributing)
 
 ## Quickstart
@@ -45,8 +52,8 @@ ENVied.require
 ```
 
 This will throw an error if:
-* both `ENV['FORCE_SSL']` and `ENV['PORT']` are *not present*.
-* the values *cannot* be coerced to a boolean and integer.
+* one of `ENV['FORCE_SSL']`, `ENV['PORT']` is absent.
+* or: their values *cannot* be coerced (resp. to boolean and integer).
 
 ### 3) Use coerced variables
 
@@ -81,17 +88,74 @@ Add this line to your application's Gemfile:
 
 The following types are supported:
 
-* `:string` (implied)
+* `: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)
-* `:integer`
+* `: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`
-* `: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')`)
 
+
+### Key alias (unreleased)
+
+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.
+
+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.
+
+Full example:
+```
+# file: Envfile
+key_alias! { Rails.env }
+
+variable :REDIS_URL, :uri
+```
+
+Source the following in your environment:
+```
+# file: .envrc
+export REDIS_URL_DEVELOPMENT=redis://localhost:6379/0
+export REDIS_URL_TEST=redis://localhost:6379/1
+```
+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.
+
+
+#### env-type (unreleased)
+
+Variables of type `:env` take the key alias into account when accessing `ENV['FOO']`.
+
+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:
+
+```
+# file: Envfile
+
+key_alias! { Rails.env }
+
+variable :DATABASE_URL, :env
+```
+
+The following now works:
+```shell
+$ DATABASE_URL_DEVELOPMENT=postgres://localhost/blog_development rails runner "p ENV['DATABASE_URL']"
+"postgres://localhost/blog_development"
+```
+
+Note: this also works for `ENV.fetch('FOO')`.  
+Also: no coercion is done (like you would expect when accessing ENV-values directly).  
+
+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`.
+
+
 ### Groups
 
 Groups give you more flexibility to define when variables are needed.
@@ -99,7 +163,7 @@ It's similar to groups in a Gemfile:
 
 ```ruby
 # file: Envfile
-variable :FORCE_SSL, :boolean, default: 'false'
+variable :FORCE_SSL, :boolean
 
 group :production do
   variable :SECRET_KEY_BASE
@@ -131,35 +195,6 @@ ENVied.require('default')
 ENVied.require(nil)
 ```
 
-### Defaults
-
-> *NOTE*: default values will be removed in the next minor-release (i.e. > v0.9). See https://gitlab.com/envied/envied/tree/master#what-happened-to-default-values for more information and how to migrate.  
-> While your project depends on this feature it's recommended to pin the gem to 0.9-releases, i.e. `gem 'envied', '~> 0.9.3'`.
-
-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>`.
@@ -177,9 +212,55 @@ Commands:
   envied version, --version, -v  # Shows version number
 ```
 
-## How do I
+## 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
+
+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
 
-### ...find all ENV-variables my app is currently using?
+### How to find all ENV-variables my app is currently using?
 
 ```
 $ bundle exec envied extract
@@ -189,7 +270,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).
 
-### ...check the config of a Heroku app?
+### How to check the config of a Heroku app?
 
 The easiest/quickest is to run:
 
@@ -212,19 +293,38 @@ This way you can do stuff like:
 $ ./bin/heroku-env-check && git push live master
 ```
 
-## Testing
+### 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).
 
-```bash
-bundle install
-bundle exec rspec
-```
 
-## Developing
+## Development
 
 ```bash
-bin/console
+$ ./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.

data/bin/bundle

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'bundle' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "rubygems"
+
+m = Module.new do
+  module_function
+
+  def invoked_as_script?
+    File.expand_path($0) == File.expand_path(__FILE__)
+  end
+
+  def env_var_version
+    ENV["BUNDLER_VERSION"]
+  end
+
+  def cli_arg_version
+    return unless invoked_as_script? # don't want to hijack other binstubs
+    return unless "update".start_with?(ARGV.first || " ") # must be running `bundle update`
+    bundler_version = nil
+    update_index = nil
+    ARGV.each_with_index do |a, i|
+      if update_index && update_index.succ == i && a =~ Gem::Version::ANCHORED_VERSION_PATTERN
+        bundler_version = a
+      end
+      next unless a =~ /\A--bundler(?:[= ](#{Gem::Version::VERSION_PATTERN}))?\z/
+      bundler_version = $1 || ">= 0.a"
+      update_index = i
+    end
+    bundler_version
+  end
+
+  def gemfile
+    gemfile = ENV["BUNDLE_GEMFILE"]
+    return gemfile if gemfile && !gemfile.empty?
+
+    File.expand_path("../../Gemfile", __FILE__)
+  end
+
+  def lockfile
+    lockfile =
+      case File.basename(gemfile)
+      when "gems.rb" then gemfile.sub(/\.rb$/, gemfile)
+      else "#{gemfile}.lock"
+      end
+    File.expand_path(lockfile)
+  end
+
+  def lockfile_version
+    return unless File.file?(lockfile)
+    lockfile_contents = File.read(lockfile)
+    return unless lockfile_contents =~ /\n\nBUNDLED WITH\n\s{2,}(#{Gem::Version::VERSION_PATTERN})\n/
+    Regexp.last_match(1)
+  end
+
+  def bundler_version
+    @bundler_version ||= begin
+      env_var_version || cli_arg_version ||
+        lockfile_version || "#{Gem::Requirement.default}.a"
+    end
+  end
+
+  def load_bundler!
+    ENV["BUNDLE_GEMFILE"] ||= gemfile
+
+    # must dup string for RG < 1.8 compatibility
+    activate_bundler(bundler_version.dup)
+  end
+
+  def activate_bundler(bundler_version)
+    if Gem::Version.correct?(bundler_version) && Gem::Version.new(bundler_version).release < Gem::Version.new("2.0")
+      bundler_version = "< 2"
+    end
+    gem_error = activation_error_handling do
+      gem "bundler", bundler_version
+    end
+    return if gem_error.nil?
+    require_error = activation_error_handling do
+      require "bundler/version"
+    end
+    return if require_error.nil? && Gem::Requirement.new(bundler_version).satisfied_by?(Gem::Version.new(Bundler::VERSION))
+    warn "Activating bundler (#{bundler_version}) failed:\n#{gem_error.message}\n\nTo install the version of bundler this project requires, run `gem install bundler -v '#{bundler_version}'`"
+    exit 42
+  end
+
+  def activation_error_handling
+    yield
+    nil
+  rescue StandardError, LoadError => e
+    e
+  end
+end
+
+m.load_bundler!
+
+if m.invoked_as_script?
+  load Gem.bin_path("bundler", "bundle")
+end