figroll 0.0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b2c6d0f8b81e0c9f0ee662dd5a22863d3d9740b45c284d59388b2558ca2cf992
-  data.tar.gz: 712a379832929698803fb18a01cf6f1642a50cf672b9f97834fbbf293da78b5a
+  metadata.gz: 40b078c1e6ca15fa3e7643e9202c3709f80b4aa41f1976483f39b904b0f039e9
+  data.tar.gz: 36f41a5d4fc1e256583a92db385a376518a896f9ff8dcd5102496de141c26631
 SHA512:
-  metadata.gz: 358c8da70d166cb555baaaab22faac123624f87b00d316069839424eba2240c3fdc49fdaec4ef112c117c6a69cb7d66819ae3c260730beeaacf1dc08d4c6b8a9
-  data.tar.gz: f6aaf8c4eb95ad0e96a1d41001845142f0acf47ea5abe6d8b62472479b6c3b82458d4379858881f17571cd2b4c0011f1aabb13add157e88d90529767f4062901
+  metadata.gz: 0bca3e98cca1149636ecb263625c7155d9d3928a1f755cf75940faa25cf1f0ce7103739f543949b2a903cdbfdd8d030b2fffb494dc6841f77dbd8dfa978a4c28
+  data.tar.gz: eb08fcd1bb9fc67b047f9f8bf14c6d365474b7412f2d6eef4d75dad765cad093fa1bcc8f8253c6f0c25e7edee715b8251658e3dafa3666af65ec9f0a690c02f0

data/README.md

@@ -1,6 +1,12 @@
 # figroll #
 
-Figroll is a somewhat simple gem to ease your way into the use of environment variables for configuration. That said, it is not currently documented, and you should not use it just yet.
+Figroll is a somewhat simple gem to ease your way into the use of environment variables for configuration. It is not tied to any specific framework, so you can use it just about anywhere.
+
+Fetching information via Figroll works roughly like this:
+
+* If `ENV` contains the variable that you want to use, Figroll provides the data from `ENV`
+* If the varible you want to use is not in `ENV`, Figroll falls back to data provided in a YAML config file.
+* If the variable you want to use is missing from both `ENV` and the config file, Figroll raises an error.
 
 ## Installation ##
 
@@ -20,10 +26,95 @@ Or install it yourself as:
 
 ## Usage ##
 
-Wow. Just look at all this empty space. You should check back here soon, but not right now. Later than now, definitely. As in there isn't any documentation at the present moment.
+There are two aspects of usage with Figroll: Configuration and Consumption
+
+### Configuration ###
+
+To configure `Figroll` and initialize it for use, you pass a config file location to `Figroll.configure`, preferably rather early in your application's startup process. For example, in a Rails 2 application, I generally make the `configure` call towards the top of  `config/environment.rb`:
+
+```ruby
+# Bootstrap the Rails environment, frameworks, and default configuration
+require File.join(File.dirname(__FILE__), 'boot')
+require 'figroll'
+
+Rails::Initializer.run do |config|
+  Figroll.configure(File.join(File.dirname(__FILE__), 'figroll.yml'))
+
+  # ...
+end
+```
+
+#### Config File ####
+
+The Figroll configuration file is just a YAML file with specific information. Here's an example config file that shows off all of the configuration features:
+
+```yaml
+# The variables listed in "required" *must* be present either as incoming
+# environment variables (`ENV`) or via the "environments" section below.
+required:
+  - REQUIRED_VARIABLE_1
+  - REQUIRED_VARIABLE_2
+
+# The entries in the "environments" section are tied to the `FIGROLL_ENV`
+# environment variable. Each of these is in turn a list of default values for
+# that specific environment to use in case those variables are not set in the
+# execution environment.
+environments:
+  development:
+    REQUIRED_VARIABLE_1: dev 1
+    REQUIRED_VARIABLE_2: dev 2
+  staging:
+    REQUIRED_VARIABLE_1: staging 1
+    REQUIRED_VARIABLE_2: staging 2
+```
+
+***Best Practice: Use Figroll in production, but do not store a "production" environment in your Figroll config file. Instead, define the variables in production's execution environment.***
+
+#### Required Variables ####
+
+The "required" section of the config file is used to list out environment variables without which your application absolutely cannot run. A good example of such a beast is `DATABASE_URL` for the great majority of Rails apps, but we suggest making all or most of your variables required.
+
+If a variable listed in this section lacks a value at the time that `Figroll.configure` is run, the configure call raises a runtime error to reflect that missing variable. As mentioned above, it's a good idea to configure Figroll early in your application's boot process, and the specific reasoning behind that is to ensure that if there is missing configuration data, app booting fails as early as possible so you can fix it more quickly.
+
+The "required" section, however, is optional. To that end, if you leave it out, you may end up seeing fun surprises later in your application deployment's lifetime. My go-to example for this is that everything about your app may run seemingly well, but a missing payment gateway API key variable might cause checkouts to inexplicably fail.
+
+#### Variable Precedence ####
+
+The "environments" section of the Figroll config file allows one to provide default values for specific variables in case they don't appear in the execution environment.
+
+Using the above config file as an example, let's assume that `FIGROLL_ENV` is set to `staging`.
+
+If you pass this file to `Figroll.configure` with no other information in your environment, `Figroll.fetch(:required_variable_1)` will return `staging 1`.
+
+On the other hand, if `FIGROLL_ENV` is set to `staging` and `REQUIRED_VARIABLE_1` is set to `algebraic`" when you `Figroll.configure`, `Figroll.fetch(:required_variable)` will return `algebraic`.
+
+***tl;dr - Values from the execution environment have precedence over values from the Figroll config file.***
+
+### Consumption ###
+
+One consumes values from Figroll via `Figroll.fetch`, which takes either a symbol or a string as the variable name to fetch. One important consideration is that variable names in Figroll are not case-sensitive. That is, `var1` is the same as both `Var1` and `VAR1`.
+
+If you should call `Figroll.fetch` for a variable that was not known when `Figroll.configure` was called, a `RuntimeError` is raised. Otherwise, if we can resolve the requested variable name to a known variable, the value of that variable is returned.
+
+#### Consistency ####
+
+While it's easy and reasonable to think of Figroll as a proxy to `ENV`, that's not entirely accurate. Figroll only considers variables and values that are known (either in the execution environment or in the config file) at the point in time when `Figroll.configure` is called.
+
+**That is, changing an environment variable while an app is running does not affect what is returned when you `Figroll.fetch` that variable.**
+
+To that end, it would be best to avoid retrieving information directly from `ENV`.
+
+## Similar Projects ##
+
+Figroll isn't an entirely new idea at all. In this case, we're standing on the shoulders of these giants:
+
+* [figaro](https://github.com/laserlemon/figaro) is the most direct inspiration for this library, to the effect that we borrowed most of its features. The big difference is that Figroll does not automagically inject itself into your application, as it is meant to serve more frameworks than just Rails 3+. Additionally, `figaro` is a proper `ENV` proxy, so it's possible to use it somewhat interchangeably with `ENV`, and it also allows for env var mutability.
+* [dotenv](https://github.com/bkeepers/dotenv) is somewhat the grandfather of Figroll. The primary issue with it that made us want to roll our own library is that it's specifically not advised to use dotenv for production, whereas we want to do exactly that without much hoop jumping.
+* [envyable](https://github.com/philnash/envyable) is another gem that works quite a lot like Figroll. The primary difference here is that of variable precedence ... it appears that envyable favors values from its config file rather than incoming variables from the execution environment.
 
 ## History ##
 
+* 1.0.0 - Initial public release
 * 0.0.2 - Clean error message
 * 0.0.1 - A prerelease for internal tire kicking
 

data/lib/figroll.rb

@@ -1,8 +1,12 @@
 require 'figroll/config'
 require 'figroll/storage'
 
+# A simple universal ENV-focused configuration library
 module Figroll
-  def self.load_file(config_file)
+
+  # Given a config file, set up Figroll for ENV consumption
+  # @param config_file [String] the figroll configuration for your app
+  def self.configure(config_file)
     setup
 
     # Load the config file
@@ -18,45 +22,55 @@ module Figroll
     validate_configuration
   end
 
+  # Retrieve the value of an environment configuration variable. The key may be
+  # either a String or a Symbol, non-case-sensitive. For example, these all
+  # reference the same value:
+  # * 'i am a variable'
+  # * 'i_am_a_variable'
+  # * 'I_AM_A_VARIABLE'
+  # * :i_am_a_variable
+  # @param key [String, Symbol] the stringified or symbolized name of the
+  #   variable for which you want to know the value.
+  # @return [String] the value of the variable when Figroll was configured
+  # @raise [RuntimeError] if the varible was not known at configuration time
   def self.fetch(key)
     storage.fetch(key)
   end
 
-  def self.storage
-    @storage
-  end
+  class << self
+    private
 
-  def self.config
-    @config
-  end
+    def storage
+      @storage
+    end
 
-  
-  def self.validate_configuration
-    return nil if required.length == 0
-    return nil if (keys - required).length == keys.length - required.length
+    def config
+      @config
+    end
 
-    missing = required.reject {|key| keys.include?(key)}
-    raise "Required variables not set: #{missing.sort.join(', ')}"
-  end
+    def validate_configuration
+      return nil if required.length == 0
+      return nil if (keys - required).length == keys.length - required.length
 
-  def self.required
-    config.required
-  end
+      missing = required.reject {|key| keys.include?(key)}
+      raise "Required variables not set: #{missing.sort.join(', ')}"
+    end
 
-  def self.keys
-    storage.keys
-  end
+    def required
+      config.required
+    end
 
-  def self.environment
-    config.environment
-  end
+    def keys
+      storage.keys
+    end
 
-  def self.normalize(key)
-    key.to_s.upcase.gsub(/\s+/, '_')
-  end
+    def environment
+      config.environment
+    end
 
-  def self.setup
-    @config = Config.new
-    @storage = Storage.new
+    def setup
+      @config = Config.new
+      @storage = Storage.new
+    end
   end
 end

data/lib/figroll/config.rb

@@ -1,13 +1,34 @@
 require 'yaml'
+require 'figroll/util'
 
 module Figroll
+  # A configuration object for Figroll
   class Config
-    attr_reader :required, :environment, :data
 
+    # A list of required environment variables defined by the configuration
+    # @return [Array<String>, nil]
+    # @api private
+    attr_reader :required
+
+    # The `FIGROLL_ENV` under which we're running
+    # @return [String, nil]
+    # @api private
+    attr_reader :environment
+
+    # Values defined in the configuration to inject into Figroll
+    # @return [Array<String>, nil]
+    # @api private
+    attr_reader :data
+
+    # Create a new Config instance
+    # @api private
     def initialize
       reset
     end
 
+    # Given a config file name, load the configuration specified in that file.
+    # @param config_file [String]
+    # @api private
     def load_file(config_file)
       return unless File.exists?(config_file)
 
@@ -16,7 +37,7 @@ module Figroll
       # set up required keys
       file_data['required'] ||= []
       file_data['required'].each do |key|
-        required.push(Figroll.normalize(key))
+        required.push(Util.normalize(key))
       end
 
       # load up the environment-specific data

data/lib/figroll/storage.rb

@@ -1,23 +1,43 @@
+require 'figroll/util'
+
 module Figroll
+  # A storage object for Figroll
   class Storage
+    # The known variables tracked by this storage instance
+    # @return [Hash<String, String>]
+    # @api private
     attr_reader :vars
 
+    # Create a new Storage instance
+    # @api private
     def initialize
       reset
     end
 
+    # Given a key, retrieve the value stored for that key.
+    # @param key [String, Symbol] the variable for which we want a value
+    # @return [String] the value of that variable
+    # @raise [RuntimeError] if the varible is not known
+    # @api private
     def fetch(key)
-      @vars.fetch(Figroll.normalize(key))
+      @vars.fetch(Util.normalize(key))
     end
 
+    # Given a hash of variables, import those variables into the instance.
+    # @params incoming [Hash<String, String>]
+    # @return nil
+    # @api private
     def import(incoming)
       incoming.keys.each do |key|
-        vars[Figroll.normalize(key)] = incoming[key]
+        vars[Util.normalize(key)] = incoming[key]
       end
 
       nil
     end
 
+    # Get the list of all stored variable names
+    # @return [Array<String>]
+    # @api private
     def keys
       vars.keys
     end

data/lib/figroll/util.rb

@@ -0,0 +1,15 @@
+module Figroll
+
+  # A collection of utility methods used throughout Figroll
+  module Util
+
+    # Normalize a given key to the format generally used for environment
+    # variable names.
+    # @param key [String, Symbol] the key to normalize
+    # @return [String] the normalized key
+    def self.normalize(key)
+      key.to_s.upcase.gsub(/\s+/, '_')
+    end
+
+  end
+end

data/lib/figroll/version.rb

@@ -1,3 +1,3 @@
 module Figroll
-  VERSION = '0.0.2'
+  VERSION = '1.0.0'
 end

data/spec/figroll_spec.rb

@@ -12,26 +12,25 @@ describe Figroll do
     allow(storage).to receive(:import).and_call_original
   end
 
-  describe '.load_file' do
+  describe '.configure' do
     let(:filename) {'figroll.yml'}
     let(:config_file) {
       File.join(MOCK_PATH, filename)
     }
 
-    let(:load_file) {described_class.load_file(config_file)}
+    let(:configure) {described_class.configure(config_file)}
 
     before(:each) do
       storage.send(:reset)
       config.send(:reset)
     end
 
-    it 'forwards the call to a config object' do
-      expect(described_class.config).to eql(config)
+    it 'loads the config file via a config object' do
       expect(config).
         to receive(:load_file).
         with(config_file)
 
-      load_file
+      configure
     end
 
     context 'when there is an applicable configuration environment' do
@@ -42,7 +41,7 @@ describe Figroll do
           to receive(:import).
           with({'SAUSAGES' => 'gold'})
 
-        load_file
+        configure
       end
     end
 
@@ -51,7 +50,7 @@ describe Figroll do
         to receive(:import).
         with(ENV)
 
-      load_file
+      configure
     end
 
     context 'when there are required variables' do
@@ -63,7 +62,7 @@ describe Figroll do
         end
 
         it 'raises an error' do
-          expect {load_file}.to raise_error("Required variables not set: SAUSAGES")
+          expect {configure}.to raise_error("Required variables not set: SAUSAGES")
         end
       end
 
@@ -76,7 +75,7 @@ describe Figroll do
         end
 
         it 'raises an error' do
-          expect {load_file}.to raise_error("Required variables not set: GOLDERBLATS, SAUSAGES")
+          expect {configure}.to raise_error("Required variables not set: GOLDERBLATS, SAUSAGES")
         end
 
       end
@@ -92,7 +91,7 @@ describe Figroll do
         end
 
         it 'returns nil' do
-          expect(load_file).to eql(nil)
+          expect(configure).to eql(nil)
         end
       end
     end
@@ -101,7 +100,7 @@ describe Figroll do
       let(:filename) {'withoutreqs.yml'}
 
       it 'returns nil' do
-        expect(load_file).to eql(nil)
+        expect(configure).to eql(nil)
       end
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: figroll
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 1.0.0
 platform: ruby
 authors:
 - EY Cloud Team
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-07-18 00:00:00.000000000 Z
+date: 2019-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -97,6 +97,7 @@ files:
 - lib/figroll.rb
 - lib/figroll/config.rb
 - lib/figroll/storage.rb
+- lib/figroll/util.rb
 - lib/figroll/version.rb
 - mock/figroll.yml
 - mock/multireqs.yml