invar 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 58a64d36feebf42e3d2e44e3cee20197683055dbb276f38701344db45a050e27
+  data.tar.gz: f39265a13a4ae8a49cb2b7944599c75bab6723422d3b92f5838b777d7fa8dfab
+SHA512:
+  metadata.gz: c8d134ac530b0e9a2046922cc1055621d4120e92840eedee5fd5d527b1cd5a6880577a78cc4cbfa065dc751d48d9883a0edd36e661dcd83151b6967f1501cf6d
+  data.tar.gz: e27ee5476e9efcf5871f78e50dd428398306a2dc48092b56c55a04be3e98c30fd2fad2d899ed7d35fff70ef297d2ede51941dd22197eb56222155f8b5d93be48

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,26 @@
+inherit_from: ../.rubocop.yml
+
+AllCops:
+  Exclude:
+    - 'bin/*'
+
+  TargetRubyVersion: 2.7
+
+Layout/LineLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+# setting to 6 to match RubyMine autoformat
+Layout/FirstArrayElementIndentation:
+  IndentationWidth: 6
+
+
+# rspec blocks are huge by design
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+
+Metrics/ModuleLength:
+  Exclude:
+    - 'spec/**/*.rb'
+

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.7.1

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,49 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of
+fostering an open and welcoming community, we pledge to respect all people who
+contribute through reporting issues, posting feature requests, updating
+documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing other's private information, such as physical or electronic
+  addresses, without explicit permission
+* Other unethical or unprofessional conduct
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+By adopting this Code of Conduct, project maintainers commit themselves to
+fairly and consistently applying these principles to every aspect of managing
+this project. Project maintainers who do not follow or enforce the Code of
+Conduct may be permanently removed from the project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting a project maintainer at robin@tenjin.ca. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. Maintainers are
+obligated to maintain confidentiality with regard to the reporter of an
+incident.
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 1.3.0, available at
+[http://contributor-covenant.org/version/1/3/0/][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/3/0/

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in invar.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Robin Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,324 @@
+# Invar
+
+Single source of immutable truth for managing application configs, secrets, and environment variable data.
+
+## Big Picture
+
+Invar's main purpose is to enhance and simplify how applications know about their system environment and config.
+
+Using it in code looks like this:
+
+```ruby
+invar = Invar.new(namespace: 'my-app')
+
+db_host = invar / :config / :database / :host
+```
+
+### Background
+
+Managing application config in a [12 Factor](http://12factor.net/config) style is a good idea, but simple environment
+variables have some downsides:
+
+* They are not groupable / nestable
+* Secrets might be leaked to untrustable subprocesses or 3rd party logging services (eg. an error dump including the
+  whole ENV)
+* Secrets might be stored in plaintext (eg. in cron or scripts). It's better to store secrets as encrypted.
+* Cannot be easily checked against a schema for early error detection
+* Ruby's core ENV does not accept symbols as keys (a minor nuisance, but it counts)
+
+> **Fun Fact:** Invar is named for an [alloy used in clockmaking](https://en.wikipedia.org/wiki/Invar) - it's short for "**invar**iable".
+
+### Features
+
+Here's what this Gem provides:
+
+* File location defaults from
+  the [XDG Base Directory](https://en.wikipedia.org/wiki/Freedesktop.org#Base_Directory_Specification)
+  file location standard
+* File schema using [dry-schema](https://dry-rb.org/gems/dry-schema/main/)
+* Distinction between configs and secrets
+* Secrets encrypted using [Lockbox](https://github.com/ankane/lockbox)
+* Access configs and ENV variables using symbols or case-insensitive strings.
+* Enforced key uniqueness
+* Helpful Rake tasks
+* Meaningful error messages with suggestions
+* Immutable
+
+### Anti-Features
+
+Things that Invar intentionally does **not** support:
+
+* Multiple config sources
+    * No subtle overrides
+    * No frustration about file edits not working... because you're editing the wrong file
+    * No remembering finicky precedence order
+* Modes
+    * No forgetting to set the mode before running rake, etc
+    * No proliferation of files irrelevant to the current situation
+* Config file code interpretation (eg. ERB in YAML)
+    * Reduced security hazard
+    * No value ambiguity
+
+### But That's Bonkers
+
+It might be! This is a bit of an experiment. Some things may appear undesirable at first glance, but it's usually for a
+reason.
+
+Some situations might legitimately need a more complex configuration setup. But perhaps reflect on whether it's a code
+smell nudging you to:
+
+* Reduce your application into smaller parts (eg. microservices etc)
+* Reduce the number of service providers
+* Improve your collaboration or deployment procedures and automation
+
+You know your situation better than this README can.
+
+## Concepts and Jargon
+
+### Configurations
+
+Configurations are values that depend on the *local system environment*. They do not generally change depending on what
+you're *doing*. Examples include:
+
+* Database name
+* API options
+* Gem or library configurations
+
+### Secrets
+
+This is stuff you don't want to be read by anyone. Rails calls this concept "credentials." Examples include:
+
+* Usernames and passwords
+* API keys
+
+**This is not a replacement for a password-manager**. Use a
+proper [password sharing tool](https://en.wikipedia.org/wiki/List_of_password_managers) as the primary method for
+sharing passwords within your team. This is especially true for the master encryption key used to secure the secrets
+file.
+
+Similarly, you should use a unique encryption key for each environment (eg. your development laptop vs a server).
+
+### XDG Base Directory
+
+This is a standard that defines where applications should store their files (config, data, etc). The relevant part is
+that it looks in a couple of places for config files, declared in a pair of environment variables:
+
+1. `XDG_CONFIG_HOME`
+    - Note: Ignored when `$HOME` directory is undefined. Often the case for system daemons.
+    - Default: `~/.config/`
+2. `XDG_CONFIG_DIRS`
+    - Fallback locations, declared as a colon-separated list in priority order.
+    - Default: `/etc/xdg/`
+
+You can check your current values by running this in a terminal:
+
+    env | grep XDG
+
+### Namespace
+
+The name of the app's subdirectory under the relevant XDG Base Directory.
+
+eg:
+
+`~/.config/name-of-app`
+
+or
+
+`/etc/xdg/name-of-app`
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'invar'
+```
+
+And then run in a terminal:
+
+    bundle install
+
+## Usage
+
+### Testing
+
+Invar automatically loads the normal runtime configuration from the config files created by the Rake tasks (details in
+next section), but tests may need to override some of those values.
+
+Call `#pretend` on the relevant selector:
+
+```ruby
+# Your application require Invar as normal:
+require 'invar'
+
+invar = Invar.new(namespace: 'my-app')
+
+# ... then, in your test suite:
+require 'invar/test'
+
+# Usually this would be in a test suite hook, 
+# like Cucumber's `BeforeAll` or RSpec's `before(:all)`
+invar[:config][:theme].pretend dark_mode: true
+```
+
+Calling `#pretend` without requiring `invar/test` will raise an `ImmutableRealityError`.
+
+To override values immediately after the config files are read, use an `Invar.after_load` block:
+
+```ruby
+Invar.after_load do |invar|
+   invar[:config][:database].pretend name: 'my_app_test'
+end
+
+# This Invar will return database name 'my_app_test'
+invar = Invar.new(namespace: 'my-app')
+
+puts invar / :config / :database
+```
+
+### Rake Tasks
+
+In your `Rakefile`, add:
+
+```ruby
+require 'invar/rake'
+```
+
+Then you can use the rake tasks as reported by `rake -T`
+
+#### Show Search Paths
+
+This will show you the XDG search locations.
+
+    bundle exec rake invar:paths
+
+#### Create Config File
+
+    bundle exec rake invar:create:configs
+
+If a config file already exists in any of the search path locations, it will yell at you.
+
+#### Edit Config File
+
+    bundle exec rake invar:edit:configs
+
+#### Create Secrets File
+
+To create the config file, run this in a terminal:
+
+    bundle exec rake invar:create:secrets
+
+It will print out the generated master key. Save it to a password manager.
+
+If you do not want it to be displayed (eg. you're in public), you can pipe it to a file:
+
+    bundle exec rake invar:create:secrets > master_key
+
+Then handle the `master_key` file as needed.
+
+#### Edit Secrets File
+
+To edit the secrets file, run this and provide the file's encryption key:
+
+    bundle exec rake invar:edit:secrets
+
+The file will be decrypted and opened in your default editor (eg. nano). Once you have exited the editor, it will be
+re-encrypted (remember to save, too!).
+
+### Code
+
+Assuming file `~/.config/my-app/config.yml` with:
+
+```yml
+---
+database:
+  name: 'my_app_development'
+  host: 'localhost'
+```
+
+And an encrypted file `~/.config/my-app/secrets.yml` with:
+
+```yml
+---
+database:
+  user: 'my_app'
+  pass: 'sekret'
+```
+
+Then in `my-app.rb`, you can fetch those values:
+
+```ruby
+require 'invar'
+
+invar = Invar.new 'my-app'
+
+# Use the slash operator to fetch values (sort of like Pathname)
+puts invar / :config / :database / :host
+
+# String keys are okay, too. Also it's case-insensitive
+puts invar / 'config' / 'database' / 'host'
+
+# Secrets are kept in a separate tree 
+puts invar / :secret / :database / :username
+
+# And you can get ENV variables. This should print your HOME directory.
+puts invar / :config / :home
+
+# You can also use [] notation, which may be nicer in some situations (like #pretend)
+puts invar[:config][:database][:host]
+```
+
+> **FAQ**: Why not support a dot syntax like `invar.config.database.host`?
+>
+> **A**: Because key names could collide with method names, like `inspect`, `dup`, or `tap`.
+
+### Custom Locations
+
+You can customize the search paths by setting the environment variables `XDG_CONFIG_HOME` and/or `XDG_CONFIG_DIRS` any
+time you run a Rake task or your application.
+
+    # Looks in /tmp instead of ~/.config/ 
+    XDG_CONFIG_HOME=/tmp bundle exec rake invar:paths
+
+## Alternatives
+
+Some other gems with different approaches:
+
+- [RubyConfig](https://github.com/rubyconfig/config)
+- [Anyway Config](https://github.com/palkan/anyway_config)
+- [AppConfig](https://github.com/Oshuma/app_config)
+- [Fiagro](https://github.com/laserlemon/figaro)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/TenjinInc/invar.
+
+Valued topics:
+
+* Error messages (clarity, hinting)
+* Documentation
+* API
+* Security correctness
+
+This project is intended to be a friendly space for collaboration, and contributors are expected to adhere to the
+[Contributor Covenant](http://contributor-covenant.org) code of conduct. Play nice.
+
+### Core Developers
+
+After checking out the repo, run `bundle install` 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).
+
+Documentation is produced by Yard. Run `bundle exec rake yard`. The goal is to have 100% documentation coverage and 100%
+test coverage.
+
+Release notes are provided in `RELEASE_NOTES.md`, and should vaguely
+follow [Keep A Changelog](https://keepachangelog.com/en/1.0.0/) recommendations.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/RELEASE_NOTES.md

@@ -0,0 +1,75 @@
+# Release Notes
+
+## [Unreleased]
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* none
+
+### Bugfixes
+
+* none
+
+## [0.4.0] - 2022-12-08
+
+### Major Changes
+
+* Renamed project to Invar
+
+### Minor Changes
+
+* none
+
+### Bugfixes
+
+* `#pretend` symbolizes provided key(s)
+* `Scope#to_h` recursively calls `.to_h` on subscopes
+
+## [0.3.0] - Unreleased beta
+
+### Major Changes
+
+* none
+
+### Minor Changes
+
+* Added support for validation using dry-schema
+* Added #key? to Scope
+
+### Bugfixes
+
+* none
+
+## [0.2.0] - Unreleased beta
+
+### Major Changes
+
+* Overrides are now done with #pretend
+
+### Minor Changes
+
+* Master key is stripped of whitespace when read from file
+* Added known keys to KeyError message
+* Docs improvements
+
+### Bugfixes
+
+* none
+
+## [0.1.0] - Unreleased beta
+
+### Major Changes
+
+* Initial prototype
+
+### Minor Changes
+
+* none
+
+### Bugfixes
+
+* none

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'yard'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+YARD::Rake::YardocTask.new do |t|
+   t.files = %w[lib/**/*.rb]
+   # t.options       = %w[--some-option]
+   t.stats_options = ['--list-undoc']
+end

data/invar.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'invar/version'
+
+Gem::Specification.new do |spec|
+   spec.name    = 'invar'
+   spec.version = Invar::VERSION
+   spec.authors = ['Robin Miller']
+   spec.email   = ['robin@tenjin.ca']
+
+   spec.summary     = 'Single source of truth for environmental configuration.'
+   spec.description = <<~DESC
+      Locates and loads config YAML files based on XDG standard with the encrypted secrets file kept separately.
+      Includes useful rake tasks to make management easier. No code execution in config. Rails-independent. Gluten free.
+   DESC
+   spec.homepage = 'https://github.com/TenjinInc/invar'
+   spec.license  = 'MIT'
+   spec.metadata = {
+         'rubygems_mfa_required' => 'true'
+   }
+
+   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+   spec.bindir        = 'exe'
+   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+   spec.require_paths = ['lib']
+
+   spec.required_ruby_version = '>= 2.7'
+
+   spec.add_dependency 'dry-schema', '>= 1.0'
+   spec.add_dependency 'lockbox', '>= 1.0'
+
+   spec.add_development_dependency 'bundler', '~> 2.3'
+   spec.add_development_dependency 'fakefs', '~> 1.9'
+   spec.add_development_dependency 'rake', '~> 13.0'
+   spec.add_development_dependency 'rspec', '~> 3.12'
+   spec.add_development_dependency 'simplecov', '~> 0.21'
+   spec.add_development_dependency 'yard', '~> 0.9'
+end

data/lib/invar/file_locator.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'invar/version'
+require 'invar/scope'
+
+require 'yaml'
+require 'lockbox'
+require 'pathname'
+
+module Invar
+   # XDG values based on https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+   module XDG
+      # Default values for various XDG variables
+      module Defaults
+         # Default XDG config directory within the user's $HOME.
+         CONFIG_HOME = '~/.config'
+
+         # Default XDG config direction within the broader system paths
+         CONFIG_DIRS = '/etc/xdg'
+      end
+   end
+
+   # Common file extension constants, excluding the dot.
+   module EXT
+      # File extension for YAML files
+      YAML = 'yml'
+   end
+
+   # Locates a config file within XDG standard location(s) and namespace subdirectory.
+   class FileLocator
+      attr_reader :search_paths
+
+      # Builds a new instance that will search in the namespace.
+      #
+      # @param [String] namespace Name of the subdirectory within the XDG standard location(s)
+      # @raise [InvalidNamespaceError] if the namespace is nil or empty string
+      def initialize(namespace)
+         raise InvalidNamespaceError, 'namespace cannot be nil' if namespace.nil?
+         raise InvalidNamespaceError, 'namespace cannot be an empty string' if namespace.empty?
+
+         @namespace = namespace
+
+         home_config_dir = ENV.fetch('XDG_CONFIG_HOME', XDG::Defaults::CONFIG_HOME)
+         alt_config_dirs = ENV.fetch('XDG_CONFIG_DIRS', XDG::Defaults::CONFIG_DIRS).split(':')
+
+         source_dirs = alt_config_dirs
+         source_dirs.unshift(home_config_dir) if ENV.key? 'HOME'
+         @search_paths = source_dirs.collect { |path| Pathname.new(path) / @namespace }.collect(&:expand_path)
+
+         freeze
+      end
+
+      # Locates the file with the given same. You may optionally provide an extension as a second argument.
+      #
+      # These are equivalent:
+      #    find('config.yml')
+      #    find('config', 'yml')
+      #
+      # @param [String] basename The file's basename
+      # @param [String] ext the file extension, excluding the dot.
+      # @return [Pathname] the path of the located file
+      # @raise [AmbiguousSourceError] if the file is found in multiple locations
+      # @raise [FileNotFoundError] if the file cannot be found
+      def find(basename, ext = nil)
+         basename = [basename, ext].join('.') if ext
+
+         full_paths = search_paths.collect { |dir| dir / basename }
+         files      = full_paths.select(&:exist?)
+
+         if files.size > 1
+            msg = "Found more than 1 #{ basename } file: #{ files.join(', ') }."
+            raise AmbiguousSourceError, "#{ msg } #{ AmbiguousSourceError::HINT }"
+         end
+
+         files.first || raise(FileNotFoundError, "Could not find #{ basename }")
+      end
+
+      # Raised when the file cannot be found in any of the XDG search locations.
+      class FileNotFoundError < RuntimeError
+      end
+
+      # Raised when the provided namespace is invalid.
+      class InvalidNamespaceError < ArgumentError
+      end
+   end
+end