nvar 0.1.0

data/README.md

@@ -0,0 +1,84 @@
+# `Nvar`
+
+If your app relies on lots of environment secrets, onboarding's tough. New team members need to add credentials for fifty different services and configure no end of app settings through their environment. Worse still, if a merged PR introduces something new, it can lead to inconvenient and unpredictable errors. **`Nvar` helps keep your team in step** by making sure all necessary environment variables are set.
+
+You can use `Nvar` in Ruby apps, with out-of-the-box support provided for Rails.
+## Installation
+
+Add the gem to your Gemfile and install it with `bundle add nvar`. If you're not on Rails, you'll need to make sure that `Nvar` is required with `require 'nvar'`, and then manually call `Nvar::EnvironmentVariable.load_all` as early as is appropriate.
+## Configuration
+
+`Nvar` is configured by way of `config/environment_variables.yml`. If you're on Rails, this file will be created for you automatically. Each key corresponds to the name of a required environment variable, and houses its configuration, all of which is optional.
+
+```yml
+REQUIRED_ENV_VAR:
+  required: false # defaults to true
+  type: Integer # defaults to String
+  default_value: 8
+  filter_from_requests: true # defaults to false
+  passthrough: true # defaults to false
+```
+
+- **required** determines whether an error will be raised if the environment variable is unset during initialization.
+- **type** determines which type the variable will be cast to on load.
+- **default_value** decides the value of the environment variable if it's absent.
+- **filter_from_requests** is potentially the most exciting of the bunch - it integrates with the `vcr` gem. If your environment variable is a secret that's used directly (e.g. in bearer token authentication), use `true`. If it's used on its own as the password for basic auth, use `alone_with_basic_auth_password`. To activate the filtering, configure `VCR` as follows:
+
+```ruby
+VCR.configure do |config|
+  Nvar::EnvironmentVariable.filter_from_vcr_cassettes(config)
+end
+```
+
+Now, if you use `VCR` to record a request, that credential will be hidden using `vcr`'s `#filter_sensitive_data` hooks.
+
+This is just a glimpse of `Nvar`'s greater aim - centralizing configuration for your environment variables as much as possible. Doing so enables you to onboard developers easily, and makes it easier to hide environment variables from logs and files.
+
+### Passthrough
+
+The final config option, `passthrough`, deserves some extra detail. By default, `Nvar` sets your environment constants to their actual values in development and production environments, and to their names in test environments.
+
+In production/development, or in test with passthrough active:
+
+```
+irb(main):001:0> REQUIRED_ENV_VAR
+=> "set"
+```
+
+In test:
+
+```
+irb(main):001:0> REQUIRED_ENV_VAR
+=> "REQUIRED_ENV_VAR"
+```
+
+Your tests shouldn't be reliant on your environment, so generally, you want to have `passthrough` set to `true` as little as possible. What it *is* useful for, however, is recording VCR cassettes. Set `passthrough: true` on necessary environment variables before recording VCR cassettes, then remove it and run your tests again to make sure they're not reliant on your environment.
+
+
+## Usage
+
+Now that you've been through and configured the environment variables that are necessary for your app, `Nvar` will write your environment variables to top-level constants, cast to any types you've specified, and raise an informative error if any are absent.
+### .env files
+
+`Nvar` works well with gems like `dotenv` that source their config from a `.env` file. If an environment variable is unset when the app initializes and isn't present in `.env`, it will be added to that file. If a default value is specified in your `Nvar` config, that will be passed to `.env` too.
+
+When using gems such as `dotenv`, make sure you load those first so that the environment is ready for `Nvar` to check.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/boardfish/nvar. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/boardfish/nvar/blob/master/CODE_OF_CONDUCT.md).
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Nvar project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/boardfish/nvar/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/bin/brakeman

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'brakeman' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("brakeman", "brakeman")

data/bin/bundle-audit

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'bundle-audit' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("bundler-audit", "bundle-audit")

data/bin/bundler-audit

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'bundler-audit' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("bundler-audit", "bundler-audit")

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'nvar'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/rspec

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rspec-core", "rspec")

data/bin/rubocop

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rubocop' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rubocop", "rubocop")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/nvar/engine.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require 'rails'
+require_relative './environment_variable'
+
+module Nvar
+  class Engine < Rails::Engine # :nodoc:
+    # Load environment variables from `config/environment_variables.yml`, and assign
+    # them to constants in the app. The EnvironmentVariable class will raise an
+    # error if it can't source a required env var from the environment, and set
+    # values for use during tests.
+    config.after_initialize do |app|
+      Nvar::EnvironmentVariable.configure_for_rails(app)
+      Nvar::EnvironmentVariable.load_all
+    rescue Nvar::EnvironmentVariableNotPresentError => e
+      raise e unless Rails.env.test?
+
+      e.vars.each do |var|
+        Object.const_set(var.name, var.name)
+      end
+    end
+
+    rake_tasks do
+      load 'nvar/rails/tasks/verify_environment_file.rake'
+    end
+  end
+end

data/lib/nvar/environment_variable.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Wrapper for retrieval of environment variables. See
+# config/initializers/environment_variable_loader.rb to check out how it's used.
+require 'active_support/core_ext/hash/keys'
+require 'active_support/core_ext/object/blank'
+require 'yaml'
+
+module Nvar
+  # Wrapper for loading environment variables, used across relevant Rake tasks
+  class EnvironmentVariable
+    attr_reader :name, :type, :value, :required, :defined
+
+    def initialize(name:, type: 'String', filter_from_requests: nil, **args)
+      @name = name
+      @type = type
+      @required = args[:required].nil? ? true : args[:required]
+      @filter_from_requests = filter_from_requests.yield_self { |f| [true, false].include?(f) ? f : f&.to_sym }
+      @value = fetch_value(args.slice(:passthrough, :default_value))
+      @defined = true
+    rescue KeyError
+      @value = args[:default_value]
+      @defined = false
+    end
+
+    def to_const
+      raise Nvar::EnvironmentVariableNotPresentError, self unless defined
+
+      Object.const_set(name, typecast_value)
+    end
+
+    def set?
+      return false unless defined
+
+      return value.present? if required
+
+      true
+    end
+
+    def add_to_env_file
+      return if present_in_env_file?
+
+      File.write(Nvar.env_file_path, to_env_assign, mode: 'a')
+    end
+
+    def filter_from_vcr_cassettes(config)
+      return if @filter_from_requests.nil? || !@filter_from_requests
+
+      config.filter_sensitive_data("<#{name}>") do
+        # :nocov:
+        case @filter_from_requests
+        when :alone_as_basic_auth_password
+          Base64.encode64(['', @value].join(':')).delete("\n")
+        when true
+          @value
+        end
+        # :nocov:
+      end
+      config
+    end
+
+    private
+
+    def present_in_env_file?
+      File.open(Nvar.env_file_path) { |f| f.each_line.find { |line| line.start_with?("#{name}=") } }
+    end
+
+    def to_env_assign
+      "#{name}=#{value}\n"
+    end
+
+    def typecast_value
+      return value if value.nil?
+
+      Kernel.public_send(type.to_sym, value)
+    end
+
+    def fetch_value(passthrough: false, default_value: nil)
+      return (default_value || name) if ENV['RAILS_ENV'] == 'test' && !passthrough
+
+      required ? ENV.fetch(name.to_s) : ENV[name.to_s]
+    end
+  end
+end

data/lib/nvar/rails/tasks/verify_environment_file.rake

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+namespace :nvar do
+  task :verify_environment_file do
+    Nvar::EnvironmentVariable.configure_for_rails(Rails)
+    Nvar::EnvironmentVariable.verify_env ? exit : exit(1)
+  end
+end

data/lib/nvar/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Nvar
+  VERSION = '0.1.0'
+end

data/lib/nvar.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'nvar/version'
+require 'nvar/environment_variable'
+require 'nvar/engine' if defined?(Rails)
+require 'active_support/core_ext/module/attribute_accessors'
+
+# Centralized configuration for required environment variables in your Ruby app.
+module Nvar
+  mattr_accessor :config_file_path, default: File.expand_path('config/environment_variables.yml')
+  mattr_accessor :env_file_path, default: File.expand_path('.env')
+
+  # Comments in .env files must have a leading '#' symbol. This cannot be
+  # followed by a space.
+  ENV_COMMENT = <<~'COMMENT'
+    #Environment variables are managed through this file (.env). The Scripts to
+    #Rule Them All (in script/) load the environment from here, and the app warns
+    #on startup if any required environment variables are missing. You can see the
+    #list of environment variables that can be set for the app in
+    #config/environment_variables.yml.
+  COMMENT
+
+  class Error < StandardError; end
+
+  # Error that is raised when an environment variable is blank or unset when it is
+  # required
+  class EnvironmentVariableNotPresentError < Error
+    attr_reader :vars
+
+    def initialize(*vars)
+      @vars = vars
+      super()
+    end
+
+    def message
+      "The following variables are unset or blank: #{vars.map(&:name).join(', ')}"
+    end
+  end
+
+  class << self
+    def configure_for_rails(app)
+      self.config_file_path = app.root.join('config/environment_variables.yml')
+      self.env_file_path = app.root.join('.env')
+      [config_file_path, env_file_path].each do |path|
+        File.open(path, 'w') {} unless path.exist? # rubocop:disable Lint/EmptyBlock
+      end
+    end
+
+    def load_all
+      all.tap do |set, unset|
+        set.map(&:to_const)
+        raise EnvironmentVariableNotPresentError.new(*unset) if unset.any?
+      end
+    end
+
+    def filter_from_vcr_cassettes(config)
+      set, = all
+      set.reduce(config) do |c, env_var|
+        c.tap { env_var.filter_from_vcr_cassettes(c) }
+      end
+    end
+
+    def all
+      variables.map do |variable_name, config|
+        EnvironmentVariable.new(**(config || {}).merge(name: variable_name))
+      end.partition(&:set?)
+    end
+
+    def touch_env
+      File.write(env_file_path, ENV_COMMENT, mode: 'w') unless File.exist?(env_file_path)
+    end
+
+    def verify_env(write_to_file: true)
+      _set, unset = all
+      return true if all_required_env_variables_set?
+
+      puts 'Please update .env with values for each environment variable:'
+      touch_env if write_to_file
+      unset.each do |variable|
+        variable.add_to_env_file if write_to_file
+        puts "- #{variable.name}"
+      end
+      puts "#{config_file_path} contains information on required environment variables across the app."
+      # Don't exit if all unset variables had defaults that were written to .env
+      write_to_file && unset.all? { |variable| variable.value.present? }
+    end
+
+    private
+
+    def all_required_env_variables_set?
+      all[1].none? || ENV['RAILS_ENV'] == 'test'
+    end
+
+    def variables
+      (YAML.safe_load(File.read(config_file_path)) || {}).deep_symbolize_keys
+    end
+  end
+end

data/nvar.gemspec

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative 'lib/nvar/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'nvar'
+  spec.version       = Nvar::VERSION
+  spec.authors       = ['Simon Fish']
+  spec.email         = ['si@mon.fish']
+
+  spec.summary       = 'Manage environment variables in Ruby'
+  spec.description   = 'Manage environment variables in Ruby'
+  spec.homepage      = 'https://github.com/boardfish/nvar'
+  spec.license       = 'MIT'
+  spec.required_ruby_version = Gem::Requirement.new('>= 2.7.0')
+
+  spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+  spec.add_runtime_dependency     'activesupport', ['>= 5.0.0', '< 8.0']
+  spec.add_development_dependency 'bundler-audit'
+  spec.add_development_dependency 'byebug'
+  spec.add_development_dependency 'climate_control'
+  spec.add_development_dependency 'rails'
+  spec.add_development_dependency 'rubocop', '~> 1.12.0'
+  spec.add_development_dependency 'rubocop-rake'
+  spec.add_development_dependency 'rubocop-rspec'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'tempfile'
+  spec.add_development_dependency 'vcr'
+  spec.metadata = {
+    'rubygems_mfa_required' => 'true'
+  }
+end

data/script/create-sample-app

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Exit if repo already exists
+[ -d "replicate-bug" ] && echo "Sample repo exists. Rename or remove it to begin." && exit
+branch_name=$(git rev-parse --abbrev-ref HEAD)
+# Ensure that when we install nvar in the repo, we install this copy.
+bundle config local.nvar $(pwd)
+# Create and enter a minimal example repo
+rails new --minimal replicate-bug
+cd replicate-bug
+# Add our local copy of ViewComponent
+bundle add nvar --git https://github.com/boardfish/nvar --branch $branch_name
+# Generate a controller
+rails g controller Home index
+# Root to the index action on HomeController
+cat << 'ROUTES' > 'config/routes.rb'
+Rails.application.routes.draw do
+  root to: 'home#index'
+end
+ROUTES