complex_config 0.22.3 → 0.23.0

data/Rakefile

@@ -11,10 +11,11 @@ GemHadar do
   description 'This library allows you to access configuration files via a simple interface'
   executables 'complex_config'
   test_dir    'spec'
-  ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', 'coverage', '.rvmrc',
-    '.AppleDouble', '.DS_Store', 'errors.lst', 'tags'
+  ignore      '.*.sw[pon]', 'pkg', 'Gemfile.lock', 'coverage',
+    '.AppleDouble', '.DS_Store', 'errors.lst', 'tags', 'cscope.out', 'doc',
+    '.yardoc'
   package_ignore '.all_images.yml', '.utilsrc', '.rspec', '.tool-versions',
-    '.gitignore'
+    '.gitignore', '.contexts'
 
   readme      'README.md'
   title       "#{name.camelize} -- configuration library"
@@ -31,7 +32,8 @@ GemHadar do
   development_dependency 'rspec'
   development_dependency 'monetize'
   development_dependency 'debug'
-  development_dependency 'all_images', '~> 0.8'
+  development_dependency 'all_images',    '~> 0.8'
+  development_dependency 'context_spook', '~> 0.4'
 end
 
 task :default => :spec

data/VERSION

@@ -1 +1 @@
-0.22.3
+0.23.0

data/bin/complex_config

@@ -1,4 +1,14 @@
 #!/usr/bin/env ruby
+#
+# Complex Config Manager
+#
+# A command-line tool for managing encrypted configuration files.
+#
+# Features:
+# - Edit, encrypt, decrypt, and display configuration files
+# - Generate new encryption keys
+# - Re-encrypt files with different keys
+# - Secure file operations to prevent data corruption
 
 require 'complex_config/rude'
 require 'tins/xt'
@@ -9,6 +19,14 @@ include FileUtils
 
 $opts = go 'o:n:h'
 
+# The usage method displays help information and exits the program
+#
+# This method outputs a formatted help message to the standard output,
+# including usage instructions, available commands, and options. It then
+# terminates the program with the specified exit code.
+#
+# @param msg [String] the help message to display
+# @param rc [Integer] the exit code to use when terminating the program
 def usage(msg: 'Displaying help', rc: 0)
   puts <<~end
     #{msg}
@@ -32,6 +50,15 @@ def usage(msg: 'Displaying help', rc: 0)
   exit rc
 end
 
+# The fetch_filename method processes and validates a configuration filename
+#
+# This method retrieves a filename from the command line arguments, verifies
+# its existence, and optionally ensures it has the correct file extension
+# suffix. It handles validation for encrypted configuration files and provides
+# appropriate error messages when requirements are not met.
+#
+# @param suffix [TrueClass, FalseClass] whether to validate or remove the .enc suffix
+# @return [String] the validated filename without the .enc suffix if requested
 def fetch_filename(suffix: true)
   fn = ARGV.shift.dup or usage msg: "config filename required", rc: 1
   if suffix
@@ -105,7 +132,10 @@ when 'recrypt'
     f.write(recrypted_text)
     mv encrypted_fn + '.enc', encrypted_fn + '.enc.bak'
   end
-  puts "File was recrypted as #{(encrypted_fn + '.enc').inspect}. You can remove #{(encrypted_fn + '.enc.bak').inspect} now."
+  puts <<~EOT
+    File was recrypted as #{(encrypted_fn + '.enc').inspect}.
+    You can remove #{(encrypted_fn + '.enc.bak').inspect} now.
+  EOT
 else
   usage msg: "Unknown command #{command.inspect}", rc: 1
 end

data/complex_config.gemspec

@@ -1,9 +1,9 @@
 # -*- encoding: utf-8 -*-
-# stub: complex_config 0.22.3 ruby lib
+# stub: complex_config 0.23.0 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "complex_config".freeze
-  s.version = "0.22.3".freeze
+  s.version = "0.23.0".freeze
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0".freeze) if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib".freeze]
@@ -23,13 +23,14 @@ Gem::Specification.new do |s|
 
   s.specification_version = 4
 
-  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.4".freeze])
+  s.add_development_dependency(%q<gem_hadar>.freeze, ["~> 2.6".freeze])
   s.add_development_dependency(%q<rake>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<simplecov>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<rspec>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<monetize>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<debug>.freeze, [">= 0".freeze])
   s.add_development_dependency(%q<all_images>.freeze, ["~> 0.8".freeze])
+  s.add_development_dependency(%q<context_spook>.freeze, ["~> 0.4".freeze])
   s.add_runtime_dependency(%q<json>.freeze, [">= 0".freeze])
   s.add_runtime_dependency(%q<tins>.freeze, ["~> 1".freeze])
   s.add_runtime_dependency(%q<mize>.freeze, ["~> 0.6".freeze])

data/lib/complex_config/config.rb

@@ -1,10 +1,39 @@
 module ComplexConfig
-  Config = Struct.new('Config', :config_dir, :env, :deep_freeze, :plugins) do
+  # Configuration class for setting up ComplexConfig behavior
+  #
+  # This class provides a structured way to configure the ComplexConfig system,
+  # including environment settings, deep freezing behavior, and plugin registration.
+  #
+  # @example Basic configuration
+  #   ComplexConfig.configure do |config|
+  #     config.deep_freeze = false
+  #     config.env = 'production'
+  #   end
+  #
+  # @example Adding custom plugins
+  #   ComplexConfig.configure do |config|
+  #     config.add_plugin -> id do
+  #       if base64_string = ask_and_send("#{id}_base64")
+  #         Base64.decode64(base64_string)
+  #       else
+  #         skip
+  #       end
+  #     end
+  #   end
+  class Config < Struct.new(:config_dir, :env, :deep_freeze, :plugins)
+    # Initializes a new configuration instance
     def initialize(*)
       super
       self.plugins = []
     end
 
+    # Applies the configuration to a provider
+    #
+    # This method sets all configuration attributes on the provider and
+    # registers any plugins. It's called internally by ComplexConfig.configure.
+    #
+    # @param provider [ComplexConfig::Provider] The provider to configure
+    # @return [self] Returns self for chaining
     def configure(provider)
       each_pair do |name, value|
         value.nil? and next
@@ -17,12 +46,28 @@ module ComplexConfig
       self
     end
 
+    # Adds a plugin to the configuration
+    #
+    # Plugins are lambda expressions that can provide custom behavior for
+    # configuration attributes.
+    #
+    # @param code [Proc] The plugin code to add
+    # @return [self] Returns self for chaining
     def add_plugin(code)
       plugins << code
       self
     end
   end
 
+  # Configures the ComplexConfig system with the provided settings
+  #
+  # This is the main entry point for configuring ComplexConfig. It creates a
+  # configuration object, yields it to the provided block for customization,
+  # and applies the configuration to the provider.
+  #
+  # @yield [config] Yields the configuration object for setup
+  # @yieldparam config [Config] The configuration object to modify
+  # @return [Config] The configured object
   def self.configure
     config = Config.new
     yield config

data/lib/complex_config/encryption.rb

@@ -1,7 +1,27 @@
 require "openssl"
 require "base64"
 
+# A class that provides encryption and decryption services using AES-128-GCM
+#
+# This class handles the encryption and decryption of configuration data using
+# OpenSSL's AES-128-GCM cipher mode. It manages the encryption key validation,
+# initialization vector generation, and authentication tag handling required
+# for secure encrypted communication.
+#
+# @see ComplexConfig::EncryptionError
+# @see ComplexConfig::EncryptionKeyInvalid
+# @see ComplexConfig::DecryptionFailed
 class ComplexConfig::Encryption
+  # Initializes a new encryption instance with the specified secret key
+  #
+  # This method sets up the encryption object by validating the secret key
+  # length and preparing the OpenSSL cipher for AES-128-GCM encryption
+  # operations
+  #
+  # @param secret [String] the encryption key to use, must be exactly 16 bytes
+  #   long
+  # @raise [ComplexConfig::EncryptionKeyInvalid] if the secret key is not
+  #   exactly 16 bytes in length
   def initialize(secret)
     @secret = secret
     @secret.size != 16 and raise ComplexConfig::EncryptionKeyInvalid,
@@ -9,6 +29,19 @@ class ComplexConfig::Encryption
     @cipher = OpenSSL::Cipher.new('aes-128-gcm')
   end
 
+  # The encrypt method encodes text using AES-128-GCM encryption
+  #
+  # This method takes a text input and encrypts it using the OpenSSL cipher
+  # configured with AES-128-GCM mode. It generates a random initialization
+  # vector and authentication tag, then combines the encrypted data, IV, and
+  # auth tag into a base64-encoded string separated by '--'
+  #
+  # @param text [Object] the object to encrypt, which will be marshaled before
+  # encryption
+  #
+  # @return [String] the base64-encoded encrypted string including the
+  #   encrypted data, initialization vector, and authentication tag separated
+  #   by '--'
   def encrypt(text)
     @cipher.encrypt
     @cipher.key = @secret
@@ -25,6 +58,15 @@ class ComplexConfig::Encryption
     ].map { |v| base64_encode(v) }.join('--')
   end
 
+  # The decrypt method decodes encrypted text using AES-128-GCM decryption
+  #
+  # @param text [String] the base64-encoded encrypted string containing the
+  #   encrypted data, initialization vector, and authentication tag separated
+  #   by '--'
+  #
+  # @return [Object] the decrypted and marshaled object
+  # @raise [ComplexConfig::DecryptionFailed] if the authentication tag is
+  #   invalid or decryption fails with the provided key
   def decrypt(text)
     encrypted, iv, auth_tag = text.split('--').map { |v| base64_decode(v) }
 
@@ -47,10 +89,26 @@ class ComplexConfig::Encryption
 
   private
 
+  # The base64_encode method encodes binary data into a Base64 string format
+  #
+  # This method takes binary data as input and converts it into a
+  # Base64-encoded string representation using the strict encoding mode, which
+  # ensures that the output contains only valid Base64 characters and raises an
+  # error for invalid input
+  #
+  # @param x [Object] the binary data to encode, typically a String or binary buffer
+  # @return [String] the Base64-encoded representation of the input data
   def base64_encode(x)
     ::Base64.strict_encode64(x)
   end
 
+  # The base64_decode method decodes a Base64-encoded string back into its
+  # original binary data format.
+  #
+  # @param x [String] the Base64-encoded string to decode, which will have
+  #   leading/trailing whitespace stripped
+  # @return [String] the decoded binary data as a string
+  # @see base64_encode for the corresponding encoding method
   def base64_decode(x)
     ::Base64.strict_decode64(x.strip)
   end

data/lib/complex_config/errors.rb

@@ -1,5 +1,27 @@
 module ComplexConfig
+
+  # Abstract base class for ComplexConfig exceptions
+  #
+  # This class serves as the root of the exception hierarchy for the
+  # ComplexConfig library. All custom exceptions raised by ComplexConfig should
+  # inherit from this class.
+  #
+  # @abstract
   class ComplexConfigError < StandardError
+    # Wraps an exception with a custom error class from the ComplexConfig
+    # hierarchy
+    #
+    # This method takes an exception and wraps it with a new error class that
+    # is derived from the ComplexConfig error hierarchy. It allows for more
+    # specific error handling by converting one type of exception into another
+    # while preserving the original message and backtrace.
+    #
+    # @param klass [Class, String] The error class to wrap the exception with,
+    #   either as a Class object or a string name that can be resolved via
+    #   ComplexConfig.const_get
+    # @param e [StandardError] The original exception to be wrapped
+    # @return [ComplexConfig::ComplexConfigError] A new instance of the specified
+    #   error class containing the original exception's message and backtrace
     def self.wrap(klass, e)
       Class === klass or klass = ComplexConfig.const_get(klass)
       error = klass.new(e.message)
@@ -8,24 +30,90 @@ module ComplexConfig
     end
   end
 
+  # An exception raised when an expected configuration attribute is missing
+  #
+  # This error is triggered when code attempts to access a configuration
+  # attribute that has not been defined or set within the configuration system.
+  # It inherits from ComplexConfigError, making it part of the library's
+  # standardized exception hierarchy for consistent error handling.
+  #
+  # @see ComplexConfigError
   class AttributeMissing < ComplexConfigError
   end
 
+  # An exception raised when a required configuration file is missing
+  #
+  # This error is triggered when the system attempts to access a configuration
+  # file that cannot be found at the expected location. It inherits from
+  # ComplexConfigError, making it part of the library's standardized exception
+  # hierarchy for consistent error handling.
+  #
+  # @see ComplexConfigError
+  # @see ComplexConfig::Provider#config
+  # @see ComplexConfig::Provider#decrypt_config_case
   class ConfigurationFileMissing < ComplexConfigError
   end
 
+  # An exception raised when a configuration file has invalid syntax
+  #
+  # This error is triggered when the system encounters YAML syntax errors in
+  # configuration files that prevent them from being properly parsed. It
+  # inherits from ComplexConfigError, making it part of the library's
+  # standardized exception hierarchy for consistent error handling.
+  #
+  # @see ComplexConfigError
+  # @see ComplexConfig::Provider#config
+  # @see ComplexConfig::Provider#decrypt_config_case
   class ConfigurationSyntaxError < ComplexConfigError
   end
 
+  # An abstract base class for encryption-related errors in the ComplexConfig
+  # library.
+  #
+  # This class serves as the root of the encryption exception hierarchy,
+  # providing a common base for all encryption-specific exceptions raised by
+  # ComplexConfig.
+  #
+  # @abstract
+  # @see ComplexConfigError
   class EncryptionError < ComplexConfigError
   end
 
+  # An exception raised when an encryption key has an invalid format or length
+  #
+  # This error is triggered when an encryption key does not meet the required
+  # specifications, such as having an incorrect byte length. It inherits from
+  # EncryptionError, making it part of the library's standardized exception
+  # hierarchy for consistent error handling.
+  #
+  # @see EncryptionError
+  # @see ComplexConfig::Encryption
   class EncryptionKeyInvalid < EncryptionError
   end
 
+  # An exception raised when a required encryption key is missing
+  #
+  # This error is triggered when the system attempts to access an encryption key
+  # that cannot be found through any of the configured sources. It inherits from
+  # EncryptionError, making it part of the library's standardized exception
+  # hierarchy for consistent error handling.
+
+  # @see EncryptionError
+  # @see ComplexConfig::Encryption
+  # @see ComplexConfig::KeySource
   class EncryptionKeyMissing < EncryptionError
   end
 
+  # An exception raised when decryption operations fail
+  #
+  # This error is triggered when the system encounters issues during the
+  # decryption process, such as invalid authentication tags or cipher errors
+  # that prevent successful decryption. It inherits from EncryptionError,
+  # making it part of the library's standardized exception hierarchy for
+  # consistent error handling.
+  #
+  # @see EncryptionError
+  # @see ComplexConfig::Encryption#decrypt
   class DecryptionFailed < EncryptionError
   end
 end

data/lib/complex_config/key_source.rb

@@ -1,4 +1,18 @@
+# A key source class that provides encryption keys from various sources
+#
+# The KeySource class is responsible for managing and retrieving encryption
+# keys from different possible sources such as files, environment variables, or
+# direct values. It supports multiple configuration options and ensures that
+# only one source is used at a time.
 class ComplexConfig::KeySource
+  # The initialize method sets up the key source with one of several possible settings.
+  #
+  # @param pathname [String, nil] The path to a key file
+  # @param env_var [String, nil] The name of an environment variable containing the key
+  # @param var [String, nil] A string value representing the key
+  # @param master_key_pathname [String, nil] The path to a master key file
+  #
+  # @raise [ArgumentError] if more than one setting is provided
   def initialize(pathname: nil, env_var: nil, var: nil, master_key_pathname: nil)
     settings = [ pathname, env_var, var, master_key_pathname ].compact.size
     if settings > 1
@@ -10,10 +24,22 @@ class ComplexConfig::KeySource
       pathname, env_var, var, master_key_pathname
   end
 
+  # The master_key? method checks whether a master key pathname has been set.
+  #
+  # @return [TrueClass, FalseClass] true if a master key pathname is
+  #   configured, false otherwise
   def master_key?
     !!@master_key_pathname
   end
 
+  # The key method retrieves the encryption key from the configured source.
+  #
+  # This method attempts to obtain the encryption key by checking various
+  # possible sources in order: a direct value, an environment variable,
+  # a master key file, or a key file associated with a pathname.
+  #
+  # @return [String, nil] the encryption key as a string if found, or nil if no
+  #   key source is configured or accessible
   def key
     if @var
       @var.ask_and_send(:chomp)
@@ -27,6 +53,12 @@ class ComplexConfig::KeySource
   rescue Errno::ENOENT, Errno::ENOTDIR
   end
 
+  # The key_bytes method converts the encryption key to bytes format.
+  #
+  # This method takes the encryption key value and packs it into a binary byte
+  # representation using hexadecimal encoding.
+  #
+  # @return [String] the encryption key as a binary string of bytes
   def key_bytes
     [ key ].pack('H*')
   end

data/lib/complex_config/provider/shortcuts.rb

@@ -1,5 +1,26 @@
 class ComplexConfig::Provider
+  # A module that provides convenient shortcuts for accessing configuration
+  # data
+  #
+  # This module defines methods that create proxy objects for easy
+  # configuration access with lazy evaluation and environment-specific lookups.
+  # It's designed to be included in classes that need quick access to
+  # configuration settings without explicit environment handling.
+  #
+  # @see ComplexConfig::Provider::Shortcuts
   module Shortcuts
+    # The complex_config_with_env method provides access to configuration data
+    # with explicit environment targeting.
+    #
+    # @param name [String, nil] The name of the configuration to access, or nil
+    # to return a proxy object
+    #
+    # @param env [String] The environment name to use for configuration
+    # lookups, defaults to the current provider environment
+    #
+    # @return [ComplexConfig::Settings, ComplexConfig::Proxy] Returns either
+    # the configuration settings for the specified name and environment, or a
+    # proxy object if no name is provided
     def complex_config_with_env(name = nil, env = ComplexConfig::Provider.env)
       if name
         ComplexConfig::Provider[name][env.to_s]
@@ -8,8 +29,21 @@ class ComplexConfig::Provider
       end
     end
 
+    # Alias for {complex_config_with_env}
+    # Provides a shorter syntax for accessing configuration with environment
+    # targeting.
+    #
+    # @see complex_config_with_env
     alias cc complex_config_with_env
 
+    # The complex_config method provides access to configuration data with
+    # optional name parameter.
+    #
+    # @param name [String, nil] The name of the configuration to access, or nil
+    # to return a proxy object
+    # @return [ComplexConfig::Settings, ComplexConfig::Proxy] Returns either
+    # the configuration settings for the specified name, or a proxy object if
+    # no name is provided
     def complex_config(name = nil)
       if name
         ComplexConfig::Provider[name]