configurable_from_env 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c87398f6f8863cf380719eb8e54029579cbc2941476a97b522b45a256ab996da
+  data.tar.gz: 8cbf8cf83eb5ce937b22b874fecd12e0ea8ed8161944df184cf79b0ec4d6e595
+SHA512:
+  metadata.gz: 2dfeb692f554bd8db7c5ac4d2c3c605f0eec120a82ea9565468b4a1b5c0b508c1c5bc498488719cdd5980f08e26d200a11f71c0abf6e6fe41577b6f21f09156e
+  data.tar.gz: ee98578923a3262c77e75eece7a8f7bee05f268738a2b4f81d488507f9ed2ca9c188c10856ec2c20b04a1a660b1df68b36313f63191110eb665aabef08d9a384

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Matt Brictson
+
+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,109 @@
+# configurable_from_env
+
+[![Gem Version](https://img.shields.io/gem/v/configurable_from_env)](https://rubygems.org/gems/configurable_from_env)
+[![Gem Downloads](https://img.shields.io/gem/dt/configurable_from_env)](https://www.ruby-toolbox.com/projects/configurable_from_env)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/mattbrictson/configurable_from_env/ci.yml)](https://github.com/mattbrictson/configurable_from_env/actions/workflows/ci.yml)
+[![Code Climate maintainability](https://img.shields.io/codeclimate/maintainability/mattbrictson/configurable_from_env)](https://codeclimate.com/github/mattbrictson/configurable_from_env)
+
+The `configurable_from_env` gem allows you to define accessors that automatically populate via environment variables. It works by extending Active Support's [`config_accessor`](https://api.rubyonrails.org/classes/ActiveSupport/Configurable/ClassMethods.html#method-i-config_accessor) with a new `:from_env` option.
+
+> [!NOTE]
+> This project is experimental. Please open an issue or send me an email and let me know what you think!
+
+---
+
+- [Quick start](#quick-start)
+- [Motivation](#motivation)
+- [Support](#support)
+- [License](#license)
+- [Code of conduct](#code-of-conduct)
+- [Contribution guide](#contribution-guide)
+
+## Quick start
+
+Add the gem to your Gemfile and run `bundle install`:
+
+```ruby
+gem "configurable_from_env"
+```
+
+Include the `ConfigurableFromEnv` mixin and then use `config_accessor` to define configurable attributes that are automatically populated from the environment.
+
+```ruby
+class MyHttpClient
+  include ConfigurableFromEnv
+
+  # Define an api_key accessor that is automatically populated from ENV["MY_API_KEY"]
+  config_accessor :api_key, from_env: "MY_API_KEY"
+
+  # Validate and convert ENV value into a desired data type
+  config_accessor :timeout, from_env: { key: "MY_TIMEOUT", type: :integer }
+
+  # Fall back to a default value if the environment variable is absent
+  config_accessor :verify_tls, from_env: { key: "MY_VERIFY_TLS", type: :boolean }, default: true
+
+  def fetch_data
+    # Config attributes are exposed as instance methods for easy access
+    conn = Faraday.new(
+      headers: { "X-API-Key" => api_key },
+      request: { timeout: timeout },
+      ssl: { verify: verify_tls }
+    )
+    conn.get("https://my.api/data")
+  end
+end
+```
+
+## Motivation
+
+Rails lacks a simple way to declare configuration dependencies on `ENV` values. Generally, the framework guides you toward one of two common approaches:
+
+**Use `ENV.fetch` directly when you need a value.** This is the most direct technique, but it means that `ENV` dependencies are scattered throughout implementation code. Testing can become more difficult due to this implicit global variable dependency, and you may need a special library to mock `ENV` access.
+
+**Define a configuration object, and use an initializer to copy values from `ENV` into the config.** Third-party gems often use this approach. Consider Devise, which uses `config/initializers/devise.rb`.
+
+```ruby
+Devise.setup do |config|
+  config.secret_key = ENV.fetch("DEVISE_SECRET_KEY")
+```
+
+This is very flexible, and works well for libraries that need to be portable across many different app environments. However for application-level code it can repetitive, as each configuration attribute has to be declared multiple times, often in 3 separate files:
+
+1. Define a configuration class that declares the attribute.
+2. Create an initializer that sets the attribute.
+3. Reference the configuration when using the attribute.
+
+**Regardless of where you put the `ENV` access, validating and converting values can be tedious.** Environment values are always strings, but often we need them to configure settings that are booleans or integers.
+
+### A different approach
+
+`configurable_from_env` is an extremely lightweight solution (~80 LOC) to the shortcomings listed above. Consider this example:
+
+```ruby
+class MyHttpClient
+  include ConfigurableFromEnv
+  config_accessor :timeout, from_env: { key: "MY_TIMEOUT", type: :integer }, default: 30
+```
+
+The benefits are:
+
+- Configurable attributes, their default values, how they map from environment variables, and their data types are all declared in one place, as opposed to scattered across initializers, classes, and/or YAML files.
+- The configuration is colocated with the code where it used (i.e. the `MyHttpClient` class, in the example).
+- Because these are simple accessors, values can be easily injected in unit tests without needing to mock `ENV`.
+- Specifying a `:type` takes care of validation and conversion of environment values with an intuitive and concise syntax.
+
+## Support
+
+If you want to report a bug, or have ideas, feedback or questions about the gem, [let me know via GitHub issues](https://github.com/mattbrictson/configurable_from_env/issues/new) and I will do my best to provide a helpful answer. Happy hacking!
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).
+
+## Code of conduct
+
+Everyone interacting in this project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](CODE_OF_CONDUCT.md).
+
+## Contribution guide
+
+Pull requests are welcome!

data/lib/configurable_from_env/environment_value.rb

@@ -0,0 +1,64 @@
+module ConfigurableFromEnv
+  class EnvironmentValue
+    TYPES = %i[boolean integer string].freeze
+
+    BOOLEAN_VALUES = {}.merge(
+      %w[1 true yes t y enable enabled on].to_h { [_1, true] },
+      %w[0 false no f n disable disabled off].to_h { [_1, false] },
+      { "" => false }
+    ).freeze
+
+    def self.from(definition)
+      return nil if definition.nil?
+
+      definition = { key: definition } unless definition.is_a?(Hash)
+      definition.assert_valid_keys(:key, :type)
+      new(**definition)
+    end
+
+    attr_reader :key, :type
+
+    def initialize(key:, type: :string, env: ENV)
+      unless TYPES.include?(type)
+        raise ArgumentError, "Invalid type: #{type.inspect} (must be one of #{TYPES.map(&:inspect).join(', ')})"
+      end
+
+      @key = key
+      @type = type
+      @env = env
+    end
+
+    def read(required: true)
+      if env.key?(key)
+        value = convert(env[key])
+        block_given? ? yield(value) : value
+      elsif required
+        raise ArgumentError, "Missing required environment variable: #{key}"
+      end
+    end
+
+    private
+
+    attr_reader :env
+
+    def convert(value)
+      send(:"convert_to_#{type}", value)
+    rescue ArgumentError
+      raise ArgumentError, "Environment variable #{key} has an invalid #{type} value: #{value.inspect}"
+    end
+
+    def convert_to_boolean(value)
+      BOOLEAN_VALUES.fetch(value&.downcase&.strip) do
+        raise ArgumentError, "Boolean value must be one of #{BOOLEAN_VALUES.keys.join(', ')}"
+      end
+    end
+
+    def convert_to_integer(value)
+      Integer(value)
+    end
+
+    def convert_to_string(value)
+      value.to_s
+    end
+  end
+end

data/lib/configurable_from_env/version.rb

@@ -0,0 +1,3 @@
+module ConfigurableFromEnv
+  VERSION = "0.1.0".freeze
+end

data/lib/configurable_from_env.rb

@@ -0,0 +1,31 @@
+require "active_support"
+require "active_support/concern"
+require "active_support/configurable"
+require "active_support/core_ext/enumerable"
+require "active_support/core_ext/hash/keys"
+
+module ConfigurableFromEnv
+  autoload :EnvironmentValue, "configurable_from_env/environment_value"
+  autoload :VERSION, "configurable_from_env/version"
+
+  extend ActiveSupport::Concern
+  include ActiveSupport::Configurable
+
+  module ClassMethods
+    def config_accessor(*attributes, from_env: nil, **options, &block)
+      if from_env && attributes.many?
+        raise ArgumentError, "Only one accessor at a time can be created using the :from_env option"
+      end
+
+      env_value = EnvironmentValue.from(from_env)
+      accessor = super(*attributes, **options, &block)
+      default_provided = options.key?(:default) || block_given?
+
+      env_value&.read(required: !default_provided) do |value|
+        public_send(:"#{attributes.first}=", value)
+      end
+
+      accessor
+    end
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: configurable_from_env
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Matt Brictson
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-11-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+description:
+email:
+- opensource@mattbrictson.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- lib/configurable_from_env.rb
+- lib/configurable_from_env/environment_value.rb
+- lib/configurable_from_env/version.rb
+homepage: https://github.com/mattbrictson/configurable_from_env
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/mattbrictson/configurable_from_env/issues
+  changelog_uri: https://github.com/mattbrictson/configurable_from_env/releases
+  source_code_uri: https://github.com/mattbrictson/configurable_from_env
+  homepage_uri: https://github.com/mattbrictson/configurable_from_env
+  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: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key:
+specification_version: 4
+summary: Define accessors that are automatically populated via ENV
+test_files: []