const_conf 0.0.0

data/Rakefile

@@ -0,0 +1,35 @@
+# vim: set filetype=ruby et sw=2 ts=2:
+
+require 'gem_hadar'
+
+GemHadar do
+  name        'const_conf'
+  module_type :module
+  author      'Florian Frank'
+  email       'flori@ping.de'
+  homepage    'https://github.com/flori/const_conf'
+  summary     'Clean DSL for config settings with validation and Rails integration'
+  description  <<~EOT
+    ConstConf is a Ruby configuration library that manages settings
+    through environment variables, files, and directories with comprehensive
+    validation and Rails integration.
+  EOT
+  test_dir    'spec'
+  ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', '.AppleDouble', '.bundle',
+    '.yardoc', 'doc', 'tags', 'coverage'
+  package_ignore '.all_images.yml', '.gitignore', 'VERSION', '.utilsrc',
+    '.github', *Dir['.contexts/*']
+  readme      'README.md'
+
+  dependency 'tins',           '~> 1.42'
+  dependency 'rails',          '~> 8'
+  dependency 'json',           '~> 2.0'
+  dependency 'complex_config', '~> 0.22'
+  development_dependency 'debug'
+  development_dependency 'rspec',         '~> 3.13'
+  development_dependency 'context_spook', '~> 0.3'
+  development_dependency 'all_images',    '~> 0.6'
+  development_dependency 'simplecov',     '~> 0.22'
+
+  licenses << 'MIT'
+end

data/const_conf.gemspec

@@ -0,0 +1,35 @@
+# -*- encoding: utf-8 -*-
+# stub: const_conf 0.0.0 ruby lib
+
+Gem::Specification.new do |s|
+  s.name = "const_conf".freeze
+  s.version = "0.0.0".freeze
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
+  s.require_paths = ["lib".freeze]
+  s.authors = ["Florian Frank".freeze]
+  s.date = "1980-01-02"
+  s.description = "ConstConf is a Ruby configuration library that manages settings\nthrough environment variables, files, and directories with comprehensive\nvalidation and Rails integration.\n".freeze
+  s.email = "flori@ping.de".freeze
+  s.extra_rdoc_files = ["README.md".freeze, "lib/const_conf.rb".freeze, "lib/const_conf/dir_plugin.rb".freeze, "lib/const_conf/env_dir_extension.rb".freeze, "lib/const_conf/errors.rb".freeze, "lib/const_conf/file_plugin.rb".freeze, "lib/const_conf/json_plugin.rb".freeze, "lib/const_conf/railtie.rb".freeze, "lib/const_conf/setting.rb".freeze, "lib/const_conf/setting_accessor.rb".freeze, "lib/const_conf/tree.rb".freeze, "lib/const_conf/version.rb".freeze, "lib/const_conf/yaml_plugin.rb".freeze]
+  s.files = ["Gemfile".freeze, "LICENSE".freeze, "README.md".freeze, "Rakefile".freeze, "const_conf.gemspec".freeze, "lib/const_conf.rb".freeze, "lib/const_conf/dir_plugin.rb".freeze, "lib/const_conf/env_dir_extension.rb".freeze, "lib/const_conf/errors.rb".freeze, "lib/const_conf/file_plugin.rb".freeze, "lib/const_conf/json_plugin.rb".freeze, "lib/const_conf/railtie.rb".freeze, "lib/const_conf/setting.rb".freeze, "lib/const_conf/setting_accessor.rb".freeze, "lib/const_conf/tree.rb".freeze, "lib/const_conf/version.rb".freeze, "lib/const_conf/yaml_plugin.rb".freeze, "spec/assets/.env/API_KEY".freeze, "spec/assets/config.json".freeze, "spec/assets/config.yml".freeze, "spec/assets/config_env.yml".freeze, "spec/const_conf/dir_plugin_spec.rb".freeze, "spec/const_conf/env_dir_extension_spec.rb".freeze, "spec/const_conf/file_plugin_spec.rb".freeze, "spec/const_conf/json_plugin_spec.rb".freeze, "spec/const_conf/setting_accessor_spec.rb".freeze, "spec/const_conf/setting_spec.rb".freeze, "spec/const_conf/tree_spec.rb".freeze, "spec/const_conf/yaml_plugin_spec.rb".freeze, "spec/const_conf_spec.rb".freeze, "spec/spec_helper.rb".freeze]
+  s.homepage = "https://github.com/flori/const_conf".freeze
+  s.licenses = ["MIT".freeze]
+  s.rdoc_options = ["--title".freeze, "ConstConf - Clean DSL for config settings with validation and Rails integration".freeze, "--main".freeze, "README.md".freeze]
+  s.rubygems_version = "3.6.9".freeze
+  s.summary = "Clean DSL for config settings with validation and Rails integration".freeze
+  s.test_files = ["spec/const_conf/dir_plugin_spec.rb".freeze, "spec/const_conf/env_dir_extension_spec.rb".freeze, "spec/const_conf/file_plugin_spec.rb".freeze, "spec/const_conf/json_plugin_spec.rb".freeze, "spec/const_conf/setting_accessor_spec.rb".freeze, "spec/const_conf/setting_spec.rb".freeze, "spec/const_conf/tree_spec.rb".freeze, "spec/const_conf/yaml_plugin_spec.rb".freeze, "spec/const_conf_spec.rb".freeze, "spec/spec_helper.rb".freeze]
+
+  s.specification_version = 4
+
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.1".freeze])
+  s.add_development_dependency(%q<debug>.freeze, [">= 0".freeze])
+  s.add_development_dependency(%q<rspec>.freeze, ["~> 3.13".freeze])
+  s.add_development_dependency(%q<context_spook>.freeze, ["~> 0.3".freeze])
+  s.add_development_dependency(%q<all_images>.freeze, ["~> 0.6".freeze])
+  s.add_development_dependency(%q<simplecov>.freeze, ["~> 0.22".freeze])
+  s.add_runtime_dependency(%q<tins>.freeze, ["~> 1.42".freeze])
+  s.add_runtime_dependency(%q<rails>.freeze, ["~> 8".freeze])
+  s.add_runtime_dependency(%q<json>.freeze, ["~> 2.0".freeze])
+  s.add_runtime_dependency(%q<complex_config>.freeze, ["~> 0.22".freeze])
+end

data/lib/const_conf/dir_plugin.rb

@@ -0,0 +1,175 @@
+# A module that provides functionality for reading file contents from
+# configuration directories, supporting XDG Base Directory Specification
+# compliance.
+#
+# The DirPlugin extends the ConstConf::Setting class to enable configuration
+# settings that are sourced from files within named directories. This allows
+# for more complex and secure configuration management, particularly useful for
+# storing sensitive data or structured configs in files rather than environment
+# variables.
+#
+# @example Basic usage with file reading
+#   module APP
+#     include ConstConf
+#     plugin ConstConf::DirPlugin
+#
+#     CONFIG_FILE = set do
+#       description 'Configuration from file'
+#       default dir('myapp', 'config.yaml')
+#       decoding { |s| YAML.load(s) }
+#     end
+#   end
+#
+# @example XDG-compliant directory structure
+#   module APP
+#     include ConstConf
+#     plugin ConstConf::DirPlugin
+#
+#     XDG_CONFIG_HOME = set do
+#       description 'XDG Config HOME'
+#       prefix ''
+#     end
+#
+#     API_KEY = set do
+#       description 'API Key from XDG config'
+#       default dir('myapp', 'api_key.txt', env_var: APP::XDG_CONFIG_HOME?)
+#     end
+#   end
+#
+# @see ConstConf::Setting
+module ConstConf::DirPlugin
+  # A configuration directory handler that provides methods for deriving
+  # directory paths, joining paths, and reading file contents from a specified
+  # directory structure.
+  #
+  # The ConfigDir class is designed to work with the XDG Base Directory
+  # Specification and supports reading files from directories with optional
+  # environment variable configuration for the root path. It provides a clean
+  # interface for accessing configuration files in a structured way.
+  class ConfigDir
+    # Initializes a new instance with a name and environment variable
+    # configuration.
+    #
+    # @param name [String] the name used to derive the directory path
+    # @param root_path [String, nil] the root path to use for deriving the directory path
+    # @param env_var [String, nil] the environment variable value to use
+    # @param env_var_name [String, nil] the name of the environment variable to look up
+    #
+    # @raise [ArgumentError] if env_var and env_var_name were given.
+    def initialize(name, root_path: nil, env_var:, env_var_name: nil)
+      !env_var.nil? && !env_var_name.nil? and
+        raise ArgumentError,
+        "need either the value of an env_var or the name env_var_name of an env_var"
+      if env_var.nil? && !env_var_name.nil?
+        env_var = ENV[env_var_name]
+      end
+      root_path ||= env_var
+      @directory_path = derive_directory_path(name, root_path)
+    end
+
+    # Returns the string representation of the configuration directory path.
+    #
+    # @return [ String ] the path of the configuration directory as a string
+    def to_s
+      @directory_path.to_s
+    end
+
+    # Joins the directory path with the given path and returns the combined
+    # result.
+    #
+    # @param path [ String ] the path to be joined with the directory path
+    #
+    # @return [ Pathname ] the combined path as a Pathname object
+    def join(path)
+      @directory_path + path
+    end
+    alias + join
+
+    # Reads the content of a file at the given path within the configuration
+    # directory.
+    #
+    # If the file exists, it returns the file's content as a string encoded in
+    # UTF-8. If a block is given and the file exists, it opens the file and
+    # yields to the block.
+    # If the file does not exist and a default value is provided, it returns
+    # the default. If a block is given and the file does not exist, it yields a
+    # StringIO object containing
+    # the default value to the block.
+    #
+    # @param path [ String ] the path to the file relative to the configuration
+    # directory
+    # @param default [ String, nil ] the default value to return if the file
+    # does not exist
+    #
+    # @yield [ io ]
+    #
+    # @return [ String, nil ] the content of the file or the default value if
+    # the file does not exist
+    def read(path, default: nil, required: false, &block)
+      full_path = join(path)
+      if File.exist?(full_path)
+        if block
+          File.open(full_path, &block)
+        else
+          File.read(full_path, encoding: 'UTF-8')
+        end
+      else
+        required and raise ConstConf::RequiredValueNotConfigured,
+          "require file at #{full_path.to_s.inspect}"
+        if default && block
+          block.(StringIO.new(default))
+        else
+          default
+        end
+      end
+    end
+
+    private
+
+    # Derives the full directory path by combining the root path and the given
+    # name.
+    #
+    # @param name [ String ] the name of the directory to be appended to the root path
+    # @param root_path [ String, nil ] the root path to use; if nil, the default root path is used
+    #
+    # @return [ Pathname ] the combined directory path as a Pathname object
+    def derive_directory_path(name, root_path)
+      root = if path = root_path
+               Pathname.new(path)
+             else
+               Pathname.new(default_root_path)
+             end
+      root + name
+    end
+
+    # Returns the default configuration directory path based on the HOME
+    # environment variable.
+    #
+    # This method constructs and returns a Pathname object pointing to the
+    # standard configuration directory location, which is typically
+    # $HOME/.config.
+    #
+    # @return [ Pathname ] the default configuration directory path
+    def default_root_path
+      Pathname.new(ENV.fetch('HOME')) + '.config'
+    end
+  end
+
+  # The dir method creates and reads a configuration directory setting.
+  #
+  # This method initializes a ConfigDir instance with the provided name and
+  # environment variable configuration, then reads the directory path with
+  # optional default and required validation settings.
+  #
+  # @param name [String] the name of the configuration directory
+  # @param path [String] the filesystem path to the directory
+  # @param env_var [String, nil] the environment variable name to use for configuration
+  # @param env_var_name [String, nil] the full environment variable name to use
+  # @param default [Object] the default value to use when no configuration is provided
+  # @param required [Boolean] whether the directory path is required to exist
+  #
+  # @return [Object] the result of reading path from the directory name
+  def dir(name, path, env_var: nil, env_var_name: nil, default: nil, required: false)
+    ConfigDir.new(name, env_var:, env_var_name:).read(path, default:, required:)
+  end
+end

data/lib/const_conf/env_dir_extension.rb

@@ -0,0 +1,83 @@
+# An extension that enables loading environment variable values from files in
+# a directory structure, where each file's basename becomes an environment
+# variable name.
+#
+# This extension is particularly useful for implementing a pattern, where each
+# environment variable is stored in its own file with the same name as the
+# variable. For example:
+#
+#   ./env/DATABASE_URL    # contains: postgresql://localhost/myapp
+#   ./env/API_KEY         # contains: sk-1234567890abcdef1234567890abcdef
+#
+# Usage:
+#   module AppConfig
+#     include ConstConf
+#
+#     description 'Application Configuration'
+#
+#     module EnvDir
+#       extend ConstConf::EnvDirExtension
+#
+#       description 'All variables loaded from .env directory'
+#
+#       # Load all environment variables from .env/*
+#       load_dotenv_dir('.env/*') {}
+#     end
+#   end
+#
+# The loaded settings are automatically:
+# - Marked as sensitive (since they might contain secrets)
+# - Required (files must exist to be loaded)
+# - Chomped to remove trailing whitespace
+# - Named using the file basename in uppercase and without a prefix.
+#
+# This extension works well alongside manually-defined settings, if you put it
+# into a nested module at the end of your ConstConf config. Settings defined
+# explicitly with `set do` blocks before this module take precedence over
+# auto-loaded ones, allowing for a hybrid approach where critical configuration
+# is documented and validated, while additional environment variables can be
+# loaded automatically from files.
+#
+# The loaded settings appear in AppConfig.view() with proper descriptions
+# showing their source file locations, making it easy to see what configuration
+# is being used.
+module ConstConf::EnvDirExtension
+  include ConstConf::FilePlugin
+
+  # Loads environment variable values from dotenv-style files into
+  # configuration constants.
+  #
+  # This method processes glob patterns to find files, reads their content
+  # using the FilePlugin, and defines configuration settings for each file's
+  # content. It automatically creates constants with uppercase names based on
+  # the filename and configures them as required and sensitive settings with
+  # chomped values.
+  #
+  # @param globs [Array<String>] glob patterns to match files containing environment variables
+  # @yield [ binding ] yields the binding of the caller to allow evaluation in the correct context
+  # @yieldparam binding [Binding] the binding to evaluate constants in
+  def load_dotenv_dir(*globs, &block)
+    block or raise ArgumentError, '&block argument is required'
+    globs.each do |glob|
+      Dir[glob].each do |path|
+        my_file = file(path, required: true)
+        eval('self', block.__send__(:binding)).class_eval do
+        name = File.basename(path).upcase
+        const_set(
+          name,
+          set do
+            prefix ''
+            description "Value of #{name.inspect} from #{File.dirname(path).inspect}"
+            default my_file
+            decode(&:chomp)
+            required true
+            sensitive true
+          end
+        )
+        rescue ConstConf::SettingAlreadyDefined
+        end
+      end
+    end
+    self
+  end
+end

data/lib/const_conf/errors.rb

@@ -0,0 +1,93 @@
+# A module that defines custom exception classes for configuration-related
+# errors in the ConstConf system. ConstConf::Errors is then included in
+# ConstConf.
+#
+# This module provides a hierarchy of exception classes that are used
+# throughout the ConstConf configuration management library to signal various
+# types of configuration issues, such as missing required values or
+# descriptions. These exceptions help ensure that applications using ConstConf
+# are properly configured and can handle configuration errors gracefully.
+#
+# @example Handling configuration errors
+#   begin
+#     # Code that may raise a ConstConf::ConfigurationError
+#   rescue ConstConf::ConfigurationError => e
+#     # Handle the configuration error appropriately
+#   end
+module ConstConf::Errors
+  # A base exception class for configuration-related errors in the ConstConf module.
+  #
+  # This class serves as the parent class for all custom exceptions raised within
+  # the ConstConf configuration management system. It provides a common ancestor
+  # for exception handling and allows for specific configuration error types to
+  # be distinguished from general errors.
+  #
+  # @example Handling a configuration error
+  #   begin
+  #     # Code that may raise a ConstConf::ConfigurationError
+  #   rescue ConstConf::ConfigurationError => e
+  #     # Handle the configuration error appropriately
+  #   end
+  class ConfigurationError < StandardError; end
+
+  # A custom exception class used to signal that a required configuration value
+  # has not been provided.
+  #
+  # This exception is raised when a configuration setting marked as required
+  # has not been configured with a valid value, helping to ensure that
+  # essential application settings are properly defined before runtime.
+  #
+  # @example Handling a required configuration error
+  #   begin
+  #     # Code that may raise RequiredValueNotConfigured
+  #   rescue RequiredValueNotConfigured => e
+  #     # Handle the missing required configuration
+  #   end
+  class RequiredValueNotConfigured < ConfigurationError ; end
+
+  # A custom exception class used to signal that a required configuration
+  # description has not been provided.
+  #
+  # This exception is raised when essential application settings are not
+  # properly documented before runtime.
+  #
+  # @example Handling a required description error
+  #   begin
+  #     # Code that may raise RequiredDescriptionNotConfigured
+  #   rescue RequiredDescriptionNotConfigured => e
+  #     # Handle the missing required configuration description
+  #   end
+  class RequiredDescriptionNotConfigured < ConfigurationError ; end
+
+  # A custom exception class raised when a configuration setting is defined
+  # more than once in the ConstConf system.
+  #
+  # This exception is used to prevent duplicate configuration settings from
+  # being registered, ensuring that each environment variable name maps to a
+  # single configuration value within a given module hierarchy.
+  #
+  # @example Handling a duplicate setting definition
+  #   begin
+  #     # Code that would cause a SettingAlreadyDefined error
+  #   rescue ConstConf::SettingAlreadyDefined => e
+  #     # Handle the duplicate setting appropriately
+  #   end
+  class SettingAlreadyDefined < ConfigurationError; end
+
+  # A custom exception class raised when a configuration setting's confirmation
+  # check fails.
+  #
+  # This exception is used to signal that a configuration setting has failed its
+  # confirmation check, which is a custom validation logic defined for the setting.
+  # It inherits from ConfigurationError and is part of the error handling mechanism
+  # within the ConstConf system to ensure settings meet specific criteria beyond
+  # basic required and default value checks.
+  #
+  # @example Handling a setting check failure
+  #   begin
+  #     # Code that may raise SettingCheckFailed
+  #   rescue ConstConf::SettingCheckFailed => e
+  #     # Handle the failed validation check appropriately
+  #   end
+  class SettingCheckFailed < ConfigurationError; end
+end

data/lib/const_conf/file_plugin.rb

@@ -0,0 +1,33 @@
+# A module that provides functionality for reading file contents as
+# configuration values.
+#
+# The FilePlugin module extends the ConstConf::Setting class to enable
+# configuration settings that are sourced from file contents rather than
+# environment variables. This allows for more complex configuration data, such
+# as SSL certificates or API keys, to be loaded from files and used within the
+# application's configuration system.
+module ConstConf::FilePlugin
+  # Reads the content of a file and returns it as a string.
+  #
+  # This method attempts to read the contents of a file specified by the given
+  # path. If the file exists, its content is returned as a string. If the file
+  # does not exist and the required flag is set to true, a
+  # RequiredValueNotConfigured exception is raised.
+  #
+  # @param path [String] the filesystem path to the file to be read
+  # @param required [Boolean] whether the file is required to exist, defaults to false
+  #
+  # @return [String, nil] the content of the file if it exists, or nil if it
+  # doesn't and required is false
+  #
+  # @raise [ConstConf::RequiredValueNotConfigured] if the file does not exist
+  # and required is true
+  def file(path, required: false)
+    if File.exist?(path)
+      File.read(path)
+    elsif required
+      raise ConstConf::RequiredValueNotConfigured,
+        "file required at path #{path.to_s.inspect}"
+    end
+  end
+end

data/lib/const_conf/json_plugin.rb

@@ -0,0 +1,12 @@
+require 'json'
+
+module ConstConf::JSONPlugin
+  def json(path, required: false, object_class: JSON::GenericObject)
+    if File.exist?(path)
+      JSON.load_file(path, object_class:)
+    elsif required
+      raise ConstConf::RequiredValueNotConfigured,
+        "JSON file required at path #{path.to_s.inspect}"
+    end
+  end
+end

data/lib/const_conf/railtie.rb

@@ -0,0 +1,13 @@
+# A Railtie implementation that integrates ConstConf with Rails application
+# initialization.
+#
+# This class ensures that configuration settings defined through ConstConf are
+# properly reloaded and synchronized when the Rails application prepares its
+# configuration, maintaining thread safety during the process.
+#
+# @example
+#   This Railtie is automatically included in a Rails application when the
+#   ConstConf gem is loaded, requiring no explicit usage in application code.
+class ConstConf::Railtie < Rails::Railtie
+  config.to_prepare { ConstConf.reload }
+end