valid-env 0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 63903d28f996a2290d7399fe50c20b2487b42749
+  data.tar.gz: 8f630092e6acfa9a2b0e4f13ebb660b4129ba39f
+SHA512:
+  metadata.gz: 2ec38fa7a2e6480456acdabb283aa9ef7a8f455a03775cdc959663a03e46b138b96b99480c7dac2eecf23d29b300b01f41f34a1de3c12a162b25fdbe373c2e58
+  data.tar.gz: 956c20d70ff91d4bb91be3dd1acafe0773a2e500b6c1c8ff3d79ed25eb5e22afd31256580267d751af9989ef18e317a665618773a21f6a22d7218c662c5a7cf9

data/README.md

@@ -0,0 +1,158 @@
+# valid-env
+## It validates environment variables
+
+We often encounter situations where our apps make use of environment variables, but sometimes only under relatively rare circumstances. It's very easy to deploy an app to a new environment, and then discover some hours (or days!) later that an important environment variable wasn't set, and some small part of the app is broken. Often the error message is cryptic.
+
+The valid-env gem provides a way to list and document not only the variables that are required, but also the relationships between them. It provides a quick way to list what's needed, and also will fail fast if the app is run when a required value is missing.
+
+## Installation
+
+```
+$ gem install valid-env
+```
+
+## Use
+
+### Required variables
+
+You've built an app that requires an environment variable, `APP_NAME`, is defined -- but that value isn't used until your code has already been running for some time.
+
+Using valid-env, you can define and wrap your environment:
+
+```ruby
+class MyEnv < ValidEnv
+  required :APP_NAME
+end
+```
+
+**In the initialization of your app, call `MyEnv.validate!`.** If `APP_NAME` is missing, this will throw a clear, readable error that explains the variable must be set.
+
+and then, replace all references to `ENV['APP_NAME']` with either
+
+```ruby
+MyEnv.APP_NAME # returns the raw env variable
+MyEnv.app_name # returns the coerced env variable value
+```
+
+Having both of these forms is more interesting when handling booleans.
+
+### Booleans
+
+Without valid-env, boolean environment variables can be a pain -- thoughtlessly changing a "true" to a "false" may not change behavior, because both are parsed as strings.
+
+ValidEnv provides a coerced value, which is falsy when the env variable is "false":
+
+
+```ruby
+class MyEnv < ValidEnv
+  required :BODGE_ENABLED, :boolean
+end
+
+# ...
+
+MyEnv.FOO_ENABLED  # returns the raw env variable (a string)
+MyEnv.foo_enabled? # returns a boolean
+```
+
+Note in the second reader method generated there is an appended '?'.
+
+### Optional variables
+
+Even if a variable isn't required, it's nice to document that it *can* exist. For this, valid-env offers the `optional` keyword:
+
+```ruby
+class MyEnv < ValidEnv
+  optional :APP_NAME
+end
+```
+
+### Conditionally required variables
+
+Some variables are required only if another variable is set.
+
+```ruby
+class MyEnv < ValidEnv
+  optional :BASIC_AUTH_REQUIRED, :boolean, default: false
+  required :BASIC_HTTP_USERNAME, if: :basic_auth_required?
+  required :BASIC_HTTP_PASSWORD, if: :basic_auth_required?
+end
+```
+
+MyEnv will only complain that `BASIC_HTTP_USERNAME` is missing if `BASIC_AUTH_REQUIRED` has been set to true.
+
+### Custom validations
+
+valid-env is built using ActiveModel::Validations; you can write your own validation methods if none of the above are suitable.
+
+```ruby
+class MyEnv < ValidEnv
+  validate :at_least_one_form_of_auth
+
+  required :PASSWORD_AUTH_ENABLED, :boolean
+  required :OAUTH_ENABLED, :boolean
+
+  def at_least_one_form_of_auth
+    has_auth = oauth_enabled? || password_auth_enabled?
+    unless has_auth
+      errors.add(:base, <<-ERR)
+        Expected at least one form of authentication to be enabled,
+        but none were. Possible forms: OAUTH, PASSWORD_AUTH
+      ERR
+    end
+  end
+end
+```
+
+### Describing the configuration
+
+`MyEnv.describe` will print out a clear list of what variables are required, which are optional, etc.
+
+### A full example
+
+```ruby
+require 'valid-env'
+
+class MyEnv < ValidEnv
+  validate :validate_at_least_one_form_of_auth
+
+  # App
+  required :APP_NAME
+  required :PASSWORD_AUTH_ENABLED, :boolean
+  optional :PING_URL
+  required :RAILS_ENV
+
+  # Amazon S3
+  required :S3_URL
+  required :S3_BUCKET
+  required :AWS_ACCESS_KEY_ID
+  required :AWS_SECRET_ACCESS_KEY
+  required :AWS_REGION
+
+  # Basic Auth
+  optional :BASIC_AUTH_REQUIRED, :boolean, default: false
+  required :BASIC_HTTP_USERNAME, if: :basic_auth_required?
+  required :BASIC_HTTP_PASSWORD, if: :basic_auth_required?
+
+  # OAuth
+  required :OAUTH_ENABLED, :boolean
+  required :OAUTH_SIGNUP_URL, if: :oauth_enabled?
+
+  required :OTHER_API_URL, if: :staging_or_production?
+
+  private
+
+  def staging_or_production?
+    %w(staging production).include? rails_env
+  end
+
+  def validate_at_least_one_form_of_auth
+    has_auth = oauth_enabled? || password_auth_enabled?
+    unless has_auth
+      errors.add(:base, <<-ERR)
+        Expected at least one form of authentication to be enabled,
+        but none were. Possible forms: OAUTH, PASSWORD_AUTH
+      ERR
+    end
+  end
+end
+```

data/lib/valid-env.rb

@@ -0,0 +1,44 @@
+require 'active_model'
+require 'active_support/core_ext/string/strip'
+
+require File.dirname(__FILE__) + '/valid-env/dsl_methods'
+# ValidEnv is the class responsible for specifying which environment variables
+# the application expects to interact with. It is so the application can
+# validate it's environment during boot.
+class ValidEnv
+  extend DslMethods
+  include ActiveModel::Validations
+
+  class Error < ::StandardError ; end
+  class InvalidEnvironment < Error ; end
+  class MissingEnvVarRegistration < Error ; end
+
+  def self.describe
+    registered_env_vars.each do |key, env_var|
+      puts env_var.to_s
+    end
+  end
+
+  def self.validate!
+    instance.validate!
+  end
+
+  def validate!
+    unless valid?
+      error_message = "Environment validation failed:\n\n"
+      errors.full_messages.each do |error|
+        error_message << "* #{error}\n"
+      end
+      error_message << "\n"
+      fail InvalidEnvironment, error_message
+    end
+  end
+end
+
+require File.dirname(__FILE__) + '/valid-env/env_var'
+require File.dirname(__FILE__) + '/valid-env/optional_env_var'
+require File.dirname(__FILE__) + '/valid-env/required_env_var'
+require File.dirname(__FILE__) + '/valid-env/boolean_validator'
+require File.dirname(__FILE__) + '/valid-env/presence_validator'
+
+

data/lib/valid-env/boolean_validator.rb

@@ -0,0 +1,15 @@
+class ValidEnv
+  class BooleanValidator < ActiveModel::EachValidator
+    def validate_each(record, attribute, value)
+      if value
+        if !['true', '1', 'false', '0'].include?(value)
+          message = options[:message] || "Environment Variable: #{attribute} was expected to be set to a boolean value, but was set to #{value.inspect}. Allowed boolean values are true (true, 1), or false (false, 0)."
+          record.errors.add :base, message
+        end
+      else
+        message = options[:message] || "Environment Variable: #{attribute} was expected to be set to a boolean, but was not set. Allowed boolean values are true (true, 1), or false (false, 0)."
+        record.errors.add :base, message
+      end
+    end
+  end
+end

data/lib/valid-env/dsl_methods.rb

@@ -0,0 +1,118 @@
+class ValidEnv
+  # DslMethods houses the DSL methods for registering ENV variables that the
+  # application knows about.
+  module DslMethods
+    # Expose a singleton-like interface for accessing an instance of ValidEnv
+    # since we only need one.
+    #
+    # Note: Don't use Singleton from Ruby standard library since that prevents
+    # us from creating ValidEnv instances in corresponding specs/tests.
+    def instance
+      @instance ||= new
+    end
+
+    # +optional+ registers an optional ENV var with the given key.
+    #
+    # == Examples
+    #
+    #    optional :FOO
+    #    optional :FOO, :boolean, default: false
+    def optional(key, type = nil, default: nil)
+      optional_env_var = OptionalEnvVar.new(
+        key,
+        type,
+        default: default
+      )
+      register_env_var(optional_env_var)
+    end
+
+    # +required+ registers a required ENV var with the given key. It supports
+    # ActiveModel#validate options.
+    #
+    # == Examples
+    #
+    #    required :BAR
+    #    required :BAR, :boolean
+    #    required :BAR, :boolean, if: :some_other_value?
+    #
+    def required(key, *args)
+      options = args.extract_options!
+      type = args.first
+      default_value = options[:default]
+      if_method = options[:if]
+
+      additional_details = "if #{if_method}" if if_method
+      required_env_var = RequiredEnvVar.new(
+        key,
+        type,
+        default: default_value,
+        additional_details: additional_details
+      )
+      register_env_var(required_env_var)
+
+      validation_args = required_env_var.boolean? ? { boolean: true } : { presence: true }
+
+      validation_args[:if] = if_method if if_method
+      validates key, **validation_args
+    end
+
+    # Override method_missing to perform a look-up on ValidEnv.instance. Every
+    # method_missing call is assumed to be an ENV var lookup.
+    #
+    #    ValidEnv.foo_enabled? -> ValidEnv.instance.foo_enabled?
+    #
+    # If ValidEnv.instance does not respond to the given method a
+    # MissingEnvVarRegistration error will be raised.
+    def method_missing(method, *args, &blk)
+      if instance.respond_to?(method)
+        instance.send(method, *args, &blk)
+      else
+        method = method.to_s
+        fail MissingEnvVarRegistration, <<-ERROR_MSG.strip_heredoc
+          undefined method #{method.inspect} for #{self}. Is the
+          #{method.upcase} env var registered in #{self}?
+        ERROR_MSG
+      end
+    end
+
+    # Returns the registered list of environment variables.
+    def registered_env_vars
+      @registered_env_vars = @registered_env_vars || {}
+    end
+
+    protected
+
+    # +register_env_var+ registers a ValidEnv::EnvVar instance and defines
+    # reader method(s) for it.
+    #
+    # Say there's a boolean EnvVar with a key of 'FOO_ENABLED'. Registering it
+    # will generate two methods:
+    #
+    #   * FOO_ENABLED - a reader method that returns the raw value of the ENV variable
+    #   * foo_enabled? - a query method that returns the boolean value
+    #
+    # Next, Say there's a EnvVar without a type with a key of 'BAR'.
+    # Registering it will generate two methods:
+    #
+    #   * BAR - a reader method that returns the raw value of the ENV variable
+    #   * bar - a query method that returns raw value
+    #
+    def register_env_var(env_var)
+      registered_env_vars[env_var.key] = env_var
+
+      # ValidEnv#APP_NAME
+      reader_method_name = env_var.key
+      define_method(reader_method_name) do
+        env_var.raw_value_from_env
+      end
+
+      # ValidEnv#app_name
+      # ValidEnv#orcid_enabled? for boolean
+      reader_method_name = "#{env_var.key.downcase}"
+      reader_method_name << "?" if env_var.boolean?
+      define_method(reader_method_name) do
+        env_var.value
+      end
+    end
+  end
+end

data/lib/valid-env/env_var.rb

@@ -0,0 +1,47 @@
+class ValidEnv
+  class EnvVar
+    attr_reader :key, :default_value, :additional_details
+
+    def initialize(key, type = nil, default: nil, additional_details: nil)
+      @key = key.to_s
+      @type = type
+      @default_value = default
+      @additional_details = additional_details
+    end
+
+    def ==(other)
+      other.is_a?(self.class) &&
+        other.key == key
+    end
+
+    def value
+      if raw_value_from_env.nil?
+        default_value
+      elsif boolean?
+        converted_boolean_value
+      else
+        raw_value_from_env
+      end
+    end
+
+    def raw_value_from_env
+      ENV[@key]
+    end
+
+    def boolean?
+      @type == :boolean
+    end
+
+    def to_s
+      msg = "Environment Variable: #{key}"
+      msg << " (#{additional_details})" if additional_details
+      msg
+    end
+
+    private
+
+    def converted_boolean_value
+      ['true', '1'].include?(raw_value_from_env.downcase)
+    end
+  end
+end

data/lib/valid-env/optional_env_var.rb

@@ -0,0 +1,10 @@
+class ValidEnv
+  class OptionalEnvVar < EnvVar
+    def to_s
+      msg = "Environment Variable: #{key} (optional"
+      msg << " #{additional_details}" if additional_details
+      msg << ")"
+      msg
+    end
+  end
+end

data/lib/valid-env/presence_validator.rb

@@ -0,0 +1,15 @@
+class ValidEnv
+  class PresenceValidator < ActiveModel::EachValidator
+    def validate_each(record, attribute, value)
+      if value
+        if value.empty?
+          message = options[:message] || "Environment Variable: #{attribute} was expected to have a value, but was set to nothing."
+          record.errors.add :base, message
+        end
+      else
+        message = options[:message] || "Environment Variable: #{attribute} was expected to be set, but was not."
+        record.errors.add :base, message
+      end
+    end
+  end
+end

data/lib/valid-env/required_env_var.rb

@@ -0,0 +1,10 @@
+class ValidEnv
+  class RequiredEnvVar < EnvVar
+    def to_s
+      msg = "Environment Variable: #{key} (required"
+      msg << " #{additional_details}" if additional_details
+      msg << ")"
+      msg
+    end
+  end
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: valid-env
+version: !ruby/object:Gem::Version
+  version: 0.0.3
+platform: ruby
+authors:
+- Zach Dennis
+- Sara Gibbons
+- Sam Bleckley
+- Mutually Human
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-06-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activemodel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.2'
+description: Valid-env allows you to specify the environment variables that are required,
+  those that are optional, and those that depend on one another, and will throw a
+  useful error message immediately if something is missing.
+email:
+- zdennis@mutuallyhuman.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/valid-env.rb
+- lib/valid-env/boolean_validator.rb
+- lib/valid-env/dsl_methods.rb
+- lib/valid-env/env_var.rb
+- lib/valid-env/optional_env_var.rb
+- lib/valid-env/presence_validator.rb
+- lib/valid-env/required_env_var.rb
+homepage: http://github.com/mhs/valid-env
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.3.6
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Ensures the environment contains the variables your code needs
+test_files: []
+has_rdoc: