figjam 1.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ef230ae6ec36d15a5f04e18d1161544166313f02919d5174ef4a73fc6fae38e2
+  data.tar.gz: b75eef364afba9fe6d50f8ccc1bb4e3cc1c10e13a8dd7a351dc14cddbaa16e46
+SHA512:
+  metadata.gz: a865580ea79bef3ff770573f20d7b6d3a66f97eb9eb8e526201342973c80e9fa8307640298e2dd29825656b6e77c65f9ed0998f64bf976f926d30c4558ad17f8
+  data.tar.gz: 3b6b0196e4fe1a80e18e9232764133c29ff4a323fd2bd864a94cf1390c796b87ad049dce634b7494d264523fadba4ec38a1eabae279c1cd235859b0fde90e7e2

data/README.md

@@ -0,0 +1,184 @@
+figjam
+================
+
+Figjam makes it easy to configure ruby and Rails apps `ENV` values by just using a single YAML file.
+
+PRs to applications often need to come with default configuration values, but hardcoding these into
+software makes them impossible to change at runtime. However supplying them separately to an
+orchestration framework introduces deploy coordination that can be tricky to get right.
+
+Figjam encourages you to commit default ENV values to a yaml file in your PRs. These are then
+loaded at runtime, but, crucially, can be overridden at any time by supplying a real ENV. This
+brings the ease of PR creation with the flexibility of runtime ENV changes.
+
+
+### Usage
+
+Add Figjam to your Gemfile and `bundle install`:
+
+```ruby
+gem "figjam"
+```
+
+Then:
+
+```bash
+$ bundle exec figjam install
+```
+
+This creates a commented `config/application.yml` file which you can add default ENV to.
+Add your own configuration to this file for all environments, and any specific environment
+overrides.
+
+### Example
+
+Given the following configuration file, the default value at the top will be used unless
+RAILS_ENV matches any of the subsequent keys (like `test`, `prelive`, `produciton`).
+
+```yaml
+# config/application.yml
+
+GOOGLE_TAG_MANAGER_ID: GTM-12345
+
+test:
+  # Use ~ for "nil"
+  GOOGLE_TAG_MANAGER_ID: ~
+  
+prelive:
+  GOOGLE_TAG_MANAGER_ID: GTM-45678
+
+production:
+  GOOGLE_TAG_MANAGER_ID: GTM-98765
+```
+
+You can then use those values in your app in an initializer, or in any other ruby code.
+
+eg:
+```
+# app/views/layouts/application.html.erb
+
+<script>
+var gtm_id = <%= ENV.fetch("GOOGLE_TAG_MANAGER_ID") %> 
+</script>
+```
+
+Note, secrets are not to be provided by figjam, so do not add them to your `application.yml`.
+
+**Please note:** `ENV` is a simple key/value store. All values will be converted
+to strings. Deeply nested configuration structures are not possible.
+
+### Using `Figjam.env`
+
+`Figjam.env` is a convenience that acts as a proxy to `ENV`.
+
+In testing, it is sometimes more convenient to stub and unstub `Figjam.env` than
+to set and reset `ENV`. Whether your application uses `ENV` or `Figjam.env` is
+entirely a matter of personal preference.
+
+```yaml
+# config/application.yml
+
+GOOGLE_TAG_MANAGER_ID: "GTM-456789"
+```
+
+```ruby
+ENV["GOOGLE_TAG_MANAGER_ID"] # => "GTM-456789"
+ENV.key?("GOOGLE_TAG_MANAGER_ID") # => true
+ENV["SOMETHING_ELSE"] # => nil
+ENV.key?("SOMETHING_ELSE") # => false
+
+Figjam.env.google_tag_manager_id # => "GTM-456789"
+Figjam.env.google_tag_manager_id? # => true
+Figjam.env.something_else # => nil
+Figjam.env.something_else? # => false
+```
+
+### Required Keys
+
+If a particular configuration value is required but not set, it's appropriate to
+raise an error. With Figjam, you can either raise these errors proactively or
+lazily.
+
+To proactively require configuration keys:
+
+```ruby
+# config/initializers/figjam.rb
+
+Figjam.require_keys("GOOGLE_TAG_MANAGER_ID")
+```
+
+If any of the configuration keys above are not set, your application will raise
+an error during initialization. This method is preferred because it prevents
+runtime errors in a production application due to improper configuration.
+
+To require configuration keys lazily, reference the variables via "bang" methods
+on `Figjam.env`:
+
+```ruby
+gtm_id = Figjam.env.google_tag_manager_id!
+```
+
+## Is Figjam like [dotenv](https://github.com/bkeepers/dotenv)?
+
+Figjam and dotenv are similar:
+
+### Similarities
+
+* Both libraries are useful for Ruby application configuration.
+* Both are inspired by Twelve-Factor App's concept of proper [configuration](http://12factor.net/config).
+* Both store configuration values in `ENV`.
+* Both can be used in and out of Rails.
+
+### Differences
+
+* Configuration File
+  * Figjam expects a single file.
+  * Dotenv supports separate files for each environment.
+* Configuration File Format
+  * Figjam expects YAML containing key/value pairs.
+  * Dotenv convention is a collection of `KEY=VALUE` pairs.
+
+If you prefer your default configuration in one place, where you can scan one file to see
+differences between environments, then you may prefer `figjam` over `dotenv`.
+
+## Is application.yml like [secrets.yml](https://github.com/rails/rails/blob/v4.1.0/railties/lib/rails/generators/rails/app/templates/config/secrets.yml)?
+
+No. Do not put secrets in `figjam` `application.yml` files! That file supposed to be committed
+to source control, and should never contain secrets.
+
+### Spring Configuration
+
+If you're using Spring add `config/application.yml` to the watch list:
+
+```rb
+# config/spring.rb
+
+%w(
+  ...
+  config/application.yml
+).each { |path| Spring.watch(path) }
+```
+
+## Figjam origins
+
+Figjam started as a direct fork of the [figaro](https://github.com/laserlemon/figaro) rubygem.
+
+There are some key differences in philosophy:
+
+1. Figjam chooses not to go down the more "use ruby for configuration" 2.x path that gem was taking,
+   preferring to keep using hierarchical yaml files.
+2. Figjam prefers that you *do* commit your application.yml to your repository, as long as you don't
+   put any credentials or other secrets in it. It encourages an ENV-with-code-change PR flow
+   that simplifies providing default ENV values for an application, as well as codified 
+   overrides per environment. These all, of course, can be overridden by a real ENV. 
+
+Given (2), it doesn't make sense to push ENV to Heroku from the application.yml file, so Heroku
+support has been removed.
+
+With those caveats, it can be used as a drop-in replacement for the `figaro` gem.
+It even aliases the `Figaro` to `Figjam` module namespace for drop-in compatibility.
+
+## How can I help?
+
+Figjam is open source and contributions from the community are encouraged! No
+contribution is too small.

data/bin/figaro

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require_relative "figjam"

data/bin/figjam

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "figjam/cli"
+
+Figjam::CLI.start

data/lib/figaro/application.rb

@@ -0,0 +1 @@
+require "figjam/application"

data/lib/figaro/rails.rb

@@ -0,0 +1 @@
+require "figjam/rails"

data/lib/figaro.rb

@@ -0,0 +1 @@
+require "figjam"

data/lib/figjam/application.rb

@@ -0,0 +1,91 @@
+require "erb"
+require "yaml"
+
+module Figjam
+  class Application
+    FIGARO_ENV_PREFIX = "_FIGARO_"
+
+    include Enumerable
+
+    def initialize(options = {})
+      @options = options.inject({}) { |m, (k, v)| m[k.to_sym] = v; m }
+    end
+
+    def path
+      @options.fetch(:path) { default_path }.to_s
+    end
+
+    def path=(path)
+      @options[:path] = path
+    end
+
+    def environment
+      environment = @options.fetch(:environment) { default_environment }
+      environment.nil? ? nil : environment.to_s
+    end
+
+    def environment=(environment)
+      @options[:environment] = environment
+    end
+
+    def configuration
+      global_configuration.merge(environment_configuration)
+    end
+
+    def load
+      each do |key, value|
+        skip?(key) ? key_skipped!(key) : set(key, value)
+      end
+    end
+
+    def each(&block)
+      configuration.each(&block)
+    end
+
+    private
+
+    def default_path
+      raise NotImplementedError
+    end
+
+    def default_environment
+      nil
+    end
+
+    def raw_configuration
+      (@parsed ||= Hash.new { |hash, path| hash[path] = parse(path) })[path]
+    end
+
+    def parse(path)
+      File.exist?(path) && YAML.load(ERB.new(File.read(path)).result) || {}
+    end
+
+    def global_configuration
+      raw_configuration.reject { |_, value| value.is_a?(Hash) }
+    end
+
+    def environment_configuration
+      raw_configuration[environment] || {}
+    end
+
+    def set(key, value)
+      non_string_configuration!(key) unless key.is_a?(String)
+      non_string_configuration!(value) unless value.is_a?(String) || value.nil?
+
+      ::ENV[key.to_s] = value.nil? ? nil : value.to_s
+      ::ENV[FIGARO_ENV_PREFIX + key.to_s] = value.nil? ? nil: value.to_s
+    end
+
+    def skip?(key)
+      ::ENV.key?(key.to_s) && !::ENV.key?(FIGARO_ENV_PREFIX + key.to_s)
+    end
+
+    def non_string_configuration!(value)
+      warn "WARNING: Use strings for Figjam configuration. #{value.inspect} was converted to #{value.to_s.inspect}."
+    end
+
+    def key_skipped!(key)
+      warn "WARNING: Skipping key #{key.inspect}. Already set in ENV."
+    end
+  end
+end

data/lib/figjam/cli/install/application.yml

@@ -0,0 +1,13 @@
+# Add configuration values here, as shown below.
+#
+# GOOGLE_TAG_MANAGER_ID: GTM-12345
+#
+# test:
+#   # Use ~ for "nil"
+#   GOOGLE_TAG_MANAGER_ID: ~
+#
+# prelive:
+#   GOOGLE_TAG_MANAGER_ID: GTM-45678
+#
+# production:
+#   GOOGLE_TAG_MANAGER_ID: GTM-98765

data/lib/figjam/cli/install.rb

@@ -0,0 +1,22 @@
+require "thor/group"
+
+module Figjam
+  class CLI < Thor
+    class Install < Thor::Group
+      include Thor::Actions
+
+      class_option "path",
+        aliases: ["-p"],
+        default: "config/application.yml",
+        desc: "Specify a configuration file path"
+
+      def self.source_root
+        File.expand_path("../install", __FILE__)
+      end
+
+      def create_configuration
+        copy_file("application.yml", options[:path])
+      end
+    end
+  end
+end

data/lib/figjam/cli/task.rb

@@ -0,0 +1,37 @@
+require "figjam/application"
+
+module Figjam
+  class CLI < Thor
+    class Task
+      attr_reader :options
+
+      def self.run(options = {})
+        new(options).run
+      end
+
+      def initialize(options = {})
+        @options = options
+      end
+
+      private
+
+      def env
+        ENV.to_hash.update(configuration)
+      end
+
+      def configuration
+        application.configuration
+      end
+
+      def application
+        @application ||= Figjam::Application.new(options)
+      end
+
+      if defined? Bundler
+        def system(*)
+          Bundler.with_clean_env { super }
+        end
+      end
+    end
+  end
+end

data/lib/figjam/cli.rb

@@ -0,0 +1,19 @@
+require "thor"
+
+module Figjam
+  class CLI < Thor
+    # figjam install
+
+    desc "install", "Install Figjam"
+
+    method_option "path",
+      aliases: ["-p"],
+      default: "config/application.yml",
+      desc: "Specify a configuration file path"
+
+    def install
+      require "figjam/cli/install"
+      Install.start
+    end
+  end
+end

data/lib/figjam/env.rb

@@ -0,0 +1,45 @@
+module Figjam
+  module ENV
+    extend self
+
+    def respond_to?(method, *)
+      key, punctuation = extract_key_from_method(method)
+
+      case punctuation
+      when "!" then has_key?(key) || super
+      when "?", nil then true
+      else super
+      end
+    end
+
+    private
+
+    def method_missing(method, *)
+      key, punctuation = extract_key_from_method(method)
+
+      case punctuation
+      when "!" then send(key) || missing_key!(key)
+      when "?" then !!send(key)
+      when nil then get_value(key)
+      else super
+      end
+    end
+
+    def extract_key_from_method(method)
+      method.to_s.downcase.match(/^(.+?)([!?=])?$/).captures
+    end
+
+    def has_key?(key)
+      ::ENV.any? { |k, _| k.downcase == key }
+    end
+
+    def missing_key!(key)
+      raise MissingKey.new(key)
+    end
+
+    def get_value(key)
+      _, value = ::ENV.detect { |k, _| k.downcase == key }
+      value
+    end
+  end
+end

data/lib/figjam/error.rb

@@ -0,0 +1,17 @@
+module Figjam
+  class Error < StandardError; end
+
+  class RailsNotInitialized < Error; end
+
+  class MissingKey < Error
+    def initialize(key)
+      super("Missing required configuration key: #{key.inspect}")
+    end
+  end
+
+  class MissingKeys < Error
+    def initialize(keys)
+      super("Missing required configuration keys: #{keys.inspect}")
+    end
+  end
+end

data/lib/figjam/rails/application.rb

@@ -0,0 +1,21 @@
+module Figjam
+  module Rails
+    class Application < Figjam::Application
+      private
+
+      def default_path
+        rails_not_initialized! unless ::Rails.root
+
+        ::Rails.root.join("config", "application.yml")
+      end
+
+      def default_environment
+        ::Rails.env
+      end
+
+      def rails_not_initialized!
+        raise RailsNotInitialized
+      end
+    end
+  end
+end

data/lib/figjam/rails/railtie.rb

@@ -0,0 +1,9 @@
+module Figjam
+  module Rails
+    class Railtie < ::Rails::Railtie
+      config.before_configuration do
+        Figjam.load
+      end
+    end
+  end
+end

data/lib/figjam/rails.rb

@@ -0,0 +1,10 @@
+begin
+  require "rails"
+rescue LoadError
+else
+  require "figjam/rails/application"
+  require "figjam/rails/railtie"
+
+  Figjam.adapter = Figjam::Rails::Application
+end
+

data/lib/figjam/version.rb

@@ -0,0 +1,6 @@
+module Figjam
+  VERSION = "1.2.0"
+end
+
+# Alias for drop-in replacement support
+Figaro = Figjam

data/lib/figjam.rb

@@ -0,0 +1,36 @@
+if Gem.loaded_specs.key?("figaro")
+  raise "The gem figjam is a replacement for figaro. Remove figaro from your Gemfile."
+end
+
+require "figjam/error"
+require "figjam/env"
+require "figjam/application"
+
+module Figjam
+  extend self
+
+  attr_writer :adapter, :application
+
+  def env
+    Figjam::ENV
+  end
+
+  def adapter
+    @adapter ||= Figjam::Application
+  end
+
+  def application
+    @application ||= adapter.new
+  end
+
+  def load
+    application.load
+  end
+
+  def require_keys(*keys)
+    missing_keys = keys.flatten - ::ENV.keys
+    raise MissingKeys.new(missing_keys) if missing_keys.any?
+  end
+end
+
+require "figjam/rails"

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: figjam
+version: !ruby/object:Gem::Version
+  version: 1.2.0
+platform: ruby
+authors:
+- Harry Lascelles
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2022-11-10 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.14.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.7.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 10.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 10.4.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+description: ENV configuration for ruby using hierarchical environment yaml files
+email:
+- harry@harrylascelles.com
+executables:
+- figjam
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/figaro
+- bin/figjam
+- lib/figaro.rb
+- lib/figaro/application.rb
+- lib/figaro/rails.rb
+- lib/figjam.rb
+- lib/figjam/application.rb
+- lib/figjam/cli.rb
+- lib/figjam/cli/install.rb
+- lib/figjam/cli/install/application.yml
+- lib/figjam/cli/task.rb
+- lib/figjam/env.rb
+- lib/figjam/error.rb
+- lib/figjam/rails.rb
+- lib/figjam/rails/application.rb
+- lib/figjam/rails/railtie.rb
+- lib/figjam/version.rb
+homepage: https://github.com/hlascelles/figjam
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hlascelles/figjam
+  documentation_uri: https://github.com/hlascelles/figjam
+  changelog_uri: https://github.com/hlascelles/figjam/blob/master/CHANGELOG.md
+  source_code_uri: https://github.com/hlascelles/figjam/
+  bug_tracker_uri: https://github.com/hlascelles/figjam/issues
+  rubygems_mfa_required: 'true'
+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: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: ENV configuration for ruby using yaml files
+test_files: []