anyway_config 2.8.1 → 2.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2505731c8729ea6a097cef8718c441684124da047a6856bd6156b4592c1ad9b
-  data.tar.gz: d20b15281220f9c3d77b7440ffcf915db6b28e6c7555ecec5ac9e4583de34887
+  metadata.gz: 5b4393c06a6078956ade1727f37879c8a38003806b59c8c5a7e9c330708a42fd
+  data.tar.gz: 98e3e7d9c0a50e2a18f98a917818ab4fa088314471102d6d6f9e67c08b059670
 SHA512:
-  metadata.gz: 70db78ae8a9859a4f660173101127d4e8d30c6a059f5b3cba121864be120a787a5998f740a948651f84c82cb22e87f7bce7926a4ad6b27352297dbc9f24d20b4
-  data.tar.gz: a314943f0a1fe0779235a75656d80cbf7a1525bbd6db24ab4fe15f508d4ac3c2790819a6d9abf39682c17c0bb0fadf4184976e9a9753dc3d61f594b910bd211a
+  metadata.gz: c9a771b5fd116be880f4aa3271a5389c6023500452eb8ea98ff8cefc5452ad0f24e3eab97bc02d39daab5231a070e4441efed4a285331d64f7f329073bfbab38
+  data.tar.gz: 8af2c0fdc71913929d78ef07f84db3b440cfa0a324834958f3bce0b77dd90e5a9c6995a61c3ba5637008171f6e02d7c7a429f46470b2d5a15984bcc524698737

data/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## master
 
+## 2.9.0 (2026-10-21)
+
+- Add an agent skill (`skills/anyway-config`) with guidance on organizing configuration in Rails apps. ([@palkan][])
+
+  The skill follows the [skills.sh](https://www.skills.sh) layout and installs automatically with [Rails Hyperdrive](https://github.com/rails-hyperdrive/rails-hyperdrive).
+
+## 2.9.0 (2026-10-20)
+
+- Add a new `enforce_config_schema` to warn or raise on unknown attributes. ([@palkan][])
+
+  When the schema is enforced, the config attributes defined in the key-based sources (YAML, credentials, etc.) must correspond to `attr_config` names in the corresponding class. Providing an unknown attribute (e.g., a typo) would raise or print a warning depending on the parameter value:
+
+```ruby
+Anyway::Settings.enforce_config_schema = true # or :warn
+
+# in Rails
+config.anyway_config.enforce_config_schema = true
+```
+
+- EJSON loader now ignores underscore-prefixed (unencrypted) keys. ([@palkan][])
+
 ## 2.8.1 (2026-07-22)
 
 - Fix default loaders order to keep ENV the last one (=higher precedence). ([@palkan][])
@@ -9,6 +30,7 @@
 - Guard against a missing `PATH` environment variable in `Anyway::Utils.which`. ([@SAY-5][])
 
 - Do not require optional loader dependencies to speed up loading. ([@ardecvz][])
+- Use `to_s` on values that support it during validation for required attributes.  This provides more consistent behaviour for the `:uri` coercer, which will otherwise produce a `#<URI::Generic >` rather than a validation failure. ([@phil-janeapp][])
 
 ## 2.8.0 (2026-06-24)
 

data/README.md

@@ -22,8 +22,9 @@ For application developers, Anyway Config could be useful to:
 **NOTE:** this readme shows documentation for 2.x version.
 For version 1.x see the [1-4-stable branch](https://github.com/palkan/anyway_config/tree/1-4-stable).
 
-<a href="https://evilmartians.com/?utm_source=anyway_config">
-<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
+<br/>
+
+<img src="https://cdn.evilmartians.com/badges/logo-no-label.svg" alt="Evil Martians logo" width="22" height="16" /> <b>Anyway Config</b> is built by <b><a href="https://evilmartians.com/">Evil Martians</a></b>, an American design and engineering consultancy for <b>developer tools, AI, and cybersecurity startups</b>.
 
 ## Links
 
@@ -33,10 +34,12 @@ For version 1.x see the [1-4-stable branch](https://github.com/palkan/anyway_con
 
 - [Main concepts](#main-concepts)
 - [Installation](#installation)
+  - [Adding agent skills](#adding-agent-skills)
 - [Usage](#usage)
   - [Configuration classes](#configuration-classes)
   - [Dynamic configuration](#dynamic-configuration)
   - [Validation & Callbacks](#validation-and-callbacks)
+  - [Enforcing config schema](#enforcing-config-schema)
 - [Using with Rails applications](#using-with-rails)
   - [Data population](#data-population)
   - [Organizing configs](#organizing-configs)
@@ -103,6 +106,18 @@ Or adding to your project:
 gem "anyway_config", "~> 2.0"
 ```
 
+### Adding agent skills
+
+The gem ships a skill for coding agents in `skills/anyway-config`. It guides an agent when it adds or changes configuration in a Rails app: where to put a config class, which source to use for a value, how to replace direct `ENV` reads, and how to test configs. It follows the [skills.sh](https://www.skills.sh) layout, so it works with any agent that reads `SKILL.md`.
+
+With [Rails Hyperdrive](https://github.com/rails-hyperdrive/rails-hyperdrive), the skill installs automatically: run `bin/rails hyperdrive:init` the first time, then `bin/rails hyperdrive:sync`.
+
+Without it, install the skill from the repository with the [skills.sh](https://www.skills.sh) CLI, or copy `skills/anyway-config` into your agent's skills directory:
+
+```sh
+npx skills add palkan/anyway_config
+```
+
 ### Supported Ruby versions
 
 - Ruby (MRI) >= 2.7.0
@@ -345,6 +360,45 @@ class MyConfig < Anyway::Config
 end
 ```
 
+### Enforcing config schema
+
+By default, Anyway Config ignores keys that don't match any of the config attributes. Thus, a typo in a YAML file (e.g., `hots` instead of `host`) goes unnoticed. You can make Anyway Config check for unknown attributes via the `enforce_config_schema` setting:
+
+```ruby
+# Raise Anyway::Config::UnknownAttributesError
+Anyway::Settings.enforce_config_schema = true
+
+# Print a warning instead
+Anyway::Settings.enforce_config_schema = :warn
+
+# Or in Rails
+config.anyway_config.enforce_config_schema = true
+```
+
+The schema is only enforced for key-based (_schemaful_) sources: YAML files, Rails credentials and secrets, and EJSON. Environment-based sources (ENV, Doppler) are never checked, since env prefixes can easily collide with unrelated variables (e.g., `AWS_PROFILE` for the `aws` config).
+
+Only top-level keys are checked; nested hashes are not validated.
+
+#### Allowing unknown attributes for some configs
+
+You can use the `rescue_unknown_attributes_with` configuration parameter to ignore specific attributes. It's called for every unknown attribute with the config object and the attribute name; return a truthy value to skip (allow) it:
+
+```ruby
+Anyway::Settings.rescue_unknown_attributes_with = ->(config, key) do
+  config.config_name == "app"
+end
+```
+
+This is particularly useful when you have multiple config classes associated with the same configurable entity (say, a service provider).
+
+#### Unknown explicit values
+
+Unknown attributes passed explicitly (`MyConfig.new(hots: "localhost")`) will raise disregards the `enforce_config_schema` setting in the future. Currently, they follow the `enforce_config_schema` configuration but we recommend to opt-in for the stricter future behaviour:
+
+```ruby
+Anyway::Settings.future.use :reject_unknown_overrides
+```
+
 ## Using with Rails
 
 **NOTE:** version 2.x supports Rails >= 6.0; for older versions use version 1.x of the gem.
@@ -825,6 +879,8 @@ class MyConfig < Anyway::Config
 end
 ```
 
+Underscore-prefixed keys (which are not encrypted by EJSON, e.g., `_public_key`) are ignored.
+
 **NOTE:** You can opt-out from EJSON loader by specifying the `ANYWAY_CONFIG_DISABLE_EJSON=true` env var (in case you have the `ejson` executable in your PATH, but don't want to use it with Anyway Config).
 
 ### Custom loaders
@@ -865,6 +921,9 @@ class ChamberConfigLoader < Base
     warn "Couldn't decrypt Chamber settings: #{e.message}"
     {}
   end
+
+  # Report unknown keys if enforce_config_schema is enabled
+  def schemaful? = true
 end
 
 # Don't forget to register it

data/lib/.rbnext/2.7/anyway/loaders/yaml.rb

@@ -28,6 +28,8 @@ module Anyway
         Utils.deep_merge!(base_config, local_config)
       end
 
+      def schemaful?() ;  true; end
+
       private
 
       def environmental?(parsed_yml)

data/lib/.rbnext/2.7/anyway/settings.rb

@@ -38,6 +38,7 @@ module Anyway
       end
 
       setting :unwrap_known_environments, true
+      setting :reject_unknown_overrides, true
 
       private
 
@@ -55,6 +56,14 @@ module Anyway
       # Suppress required validations for CI/CD pipelines
       attr_accessor :suppress_required_validations
 
+      # Whether to check for unknown attributes in schemaful (key-based) sources:
+      # false — ignore unknown attributes, true — raise, :warn — print a warning
+      attr_accessor :enforce_config_schema
+
+      # A callable (config, key) -> bool to ignore specific unknown attributes
+      # (e.g., when the same source is shared by multiple configs)
+      attr_accessor :rescue_unknown_attributes_with
+
       # A proc returning a path to YML config file given the config name
       attr_reader :default_config_path
 
@@ -113,5 +122,8 @@ module Anyway
 
     # By default, use ANYWAY_SUPPRESS_VALIDATIONS
     self.suppress_required_validations = %w[1 t true y yes].include?(ENV["ANYWAY_SUPPRESS_VALIDATIONS"])
+
+    # Unknown attributes are ignored by default
+    self.enforce_config_schema = false
   end
 end

data/lib/.rbnext/3.0/anyway/config.rb

@@ -33,6 +33,7 @@ module Anyway # :nodoc:
       deconstruct_keys
       dig
       dup
+      format_unknown_attribute
       initialize
       load
       load_from_sources
@@ -52,6 +53,8 @@ module Anyway # :nodoc:
 
     class ValidationError < Error; end
 
+    class UnknownAttributesError < ValidationError; end
+
     include OptparseConfig
     include DynamicConfig
 
@@ -374,6 +377,8 @@ module Anyway # :nodoc:
         )
 
         if overrides
+          reject_unknown_config_attributes!(overrides, source: :overrides, strict: Settings.future.reject_unknown_overrides == true)
+
           Tracing.trace!(:load) { overrides }
 
           Utils.deep_merge!(base_config, overrides)
@@ -400,10 +405,16 @@ module Anyway # :nodoc:
     def load_from_sources(base_config, **opts)
       source_filter = self.class.configuration_sources
 
-      Anyway.loaders.each do |(id, loader)|
+      Anyway.loaders.each do |(id, loader_or_proc)|
         next if source_filter && !source_filter.include?(id)
-        Utils.deep_merge!(base_config, loader.call(**opts))
+
+        loader = (loader_or_proc.is_a?(Class) && loader_or_proc <= Loaders::Base) ? loader_or_proc.new(**opts) : loader_or_proc
+        loader_data = loader.call(**opts)
+        reject_unknown_config_attributes!(loader_data, source: id) if loader.is_a?(Loaders::Base) && loader.schemaful?
+
+        Utils.deep_merge!(base_config, loader_data)
       end
+
       base_config
     end
 
@@ -460,13 +471,50 @@ module Anyway # :nodoc:
 
       self.class.required_attributes.select do |name|
         val = values.dig(*name.to_s.split(".").map(&:to_sym))
-        val.nil? || (val.is_a?(String) && val.empty?)
+        val.nil? || (val.respond_to?(:to_s) && val.to_s.empty?)
       end.then do |missing|
         next if missing.empty?
         raise_validation_error "The following config parameters for `#{self.class.name}(config_name: #{self.class.config_name})` are missing or empty: #{missing.join(", ")}"
       end
     end
 
+    def reject_unknown_config_attributes!(data, source:, strict: false)
+      return if data.nil? || data.empty?
+
+      mode = strict || Settings.enforce_config_schema
+      return unless mode
+
+      known = self.class.config_attributes.map(&:to_s)
+      unknown = data.keys.map(&:to_s) - known
+
+      unless strict
+        rescuer = Settings.rescue_unknown_attributes_with
+        unknown.reject! { |it| rescuer.call(self, it) } if rescuer
+      end
+
+      return if unknown.empty?
+
+      msg = "Unknown config attributes for `#{self.class.name || "<anonymous>"}(config_name: #{config_name})` " \
+        "provided by #{source}: #{unknown.map { |it| format_unknown_attribute(it, known) }.join(", ")}"
+
+      if strict
+        raise ArgumentError, msg
+      elsif mode == :warn
+        Kernel.warn msg
+      else
+        raise UnknownAttributesError, msg
+      end
+    end
+
+    def format_unknown_attribute(key, known)
+      return key unless defined?(::DidYouMean::SpellChecker)
+
+      suggestions = ::DidYouMean::SpellChecker.new(dictionary: known).correct(key)
+      return key if suggestions.empty?
+
+      "#{key} (did you mean: #{suggestions.join(", ")}?)"
+    end
+
     def write_config_attr(key, val)
       key = key.to_sym
       return unless self.class.config_attributes.include?(key)

data/lib/.rbnext/3.0/anyway/loaders/base.rb

@@ -11,11 +11,15 @@ module Anyway
         end
       end
 
-      def initialize(local:)
+      def initialize(local: Anyway::Settings.use_local_files, **__kwrest__)
         @local = local
       end
 
       def use_local?() ;  @local == true; end
+
+      # Whether this loader supports strict schema (so we can warn or raise on
+      # unknown attributes)
+      def schemaful?() ;  false; end
     end
   end
 end

data/lib/.rbnext/3.0/anyway/loaders/ejson.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "anyway/ejson_parser"
+
+module Anyway
+  module Loaders
+    class EJSON < Base
+      class << self
+        attr_accessor :bin_path
+      end
+
+      self.bin_path = "ejson"
+
+      def call(name:, ejson_namespace: name, ejson_parser: Anyway::EJSONParser.new(EJSON.bin_path), **_options)
+        configs = []
+
+        rel_config_paths.each do |rel_config_path|
+          secrets_hash, rel_path =
+            extract_hash_from_rel_config_path(
+              ejson_parser: ejson_parser,
+              rel_config_path: rel_config_path
+            )
+
+          next unless secrets_hash
+
+          config_hash = if ejson_namespace
+            secrets_hash[ejson_namespace]
+          else
+            secrets_hash
+          end
+
+          next unless config_hash.is_a?(Hash)
+
+          # Underscore-prefixed keys are not encrypted (e.g., _public_key)
+          config_hash = config_hash.reject { |key, _| key.start_with?("_") }
+
+          configs <<
+            trace!(:ejson, path: rel_path) do
+              config_hash
+            end
+        end
+
+        return {} if configs.empty?
+
+        configs.inject do |result_config, next_config|
+          Utils.deep_merge!(result_config, next_config)
+        end
+      end
+
+      def schemaful?() ;  true; end
+
+      private
+
+      def rel_config_paths
+        chain = [environmental_rel_config_path]
+
+        chain << "secrets.local.ejson" if use_local?
+
+        chain
+      end
+
+      def environmental_rel_config_path
+        if Settings.current_environment
+          # if environment file is absent, then take data from the default one
+          [
+            "#{Settings.current_environment}/secrets.ejson",
+            default_rel_config_path
+          ]
+        else
+          default_rel_config_path
+        end
+      end
+
+      def default_rel_config_path
+        "secrets.ejson"
+      end
+
+      def extract_hash_from_rel_config_path(ejson_parser:, rel_config_path:)
+        rel_config_path = [rel_config_path] unless rel_config_path.is_a?(Array)
+
+        rel_config_path.each do |rel_conf_path|
+          rel_path = "config/#{rel_conf_path}"
+          abs_path = "#{Settings.app_root}/#{rel_path}"
+
+          result = ejson_parser.call(abs_path)
+
+          return [result, rel_path] if result
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/.rbnext/3.0/anyway/loaders/yaml.rb

@@ -28,6 +28,8 @@ module Anyway
         Utils.deep_merge!(base_config, local_config)
       end
 
+      def schemaful?() ;  true; end
+
       private
 
       def environmental?(parsed_yml)

data/lib/.rbnext/3.0/anyway/rails/loaders/credentials.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Anyway
+  module Rails
+    module Loaders
+      class Credentials < Anyway::Loaders::Base
+        LOCAL_CONTENT_PATH = "config/credentials/local.yml.enc"
+
+        def call(name:, **_options)
+          return {} unless ::Rails.application.respond_to?(:credentials)
+
+          # do not load from credentials if we're in the context
+          # of the `credentials:edit` command
+          return {} if defined?(::Rails::Command::CredentialsCommand)
+
+          # Create a new hash cause credentials are mutable!
+          config = {}
+
+          trace!(
+            :credentials,
+            store: credentials_path
+          ) do
+            ::Rails.application.credentials.config[name.to_sym]
+          end.then do |creds|
+            Utils.deep_merge!(config, creds) if creds
+          end
+
+          if use_local?
+            trace!(:credentials, store: LOCAL_CONTENT_PATH) do
+              local_credentials(name)
+            end.then { |creds| Utils.deep_merge!(config, creds) if creds }
+          end
+
+          config
+        end
+
+        def schemaful?() ;  true; end
+
+        private
+
+        def local_credentials(name)
+          local_creds_path = ::Rails.root.join(LOCAL_CONTENT_PATH).to_s
+
+          return unless File.file?(local_creds_path)
+
+          creds = ::Rails.application.encrypted(
+            local_creds_path,
+            key_path: ::Rails.root.join("config/credentials/local.key")
+          )
+
+          creds.config[name.to_sym]
+        end
+
+        def credentials_path
+          if ::Rails.application.config.respond_to?(:credentials)
+            ::Rails.root.join(::Rails.application.config.credentials.content_path).relative_path_from(::Rails.root).to_s
+          else
+            "config/credentials.yml.enc"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/.rbnext/3.0/anyway/rails/loaders/secrets.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Anyway
+  module Rails
+    module Loaders
+      class Secrets < Anyway::Loaders::Base
+        def call(name:, **_options)
+          return {} unless ::Rails.application.respond_to?(:secrets)
+
+          # Create a new hash cause secrets are mutable!
+          config = {}
+
+          trace!(:secrets) do
+            secrets.public_send(name)
+          end.then do |secrets|
+            Utils.deep_merge!(config, secrets) if secrets
+          end
+
+          config
+        end
+
+        def schemaful?() ;  true; end
+
+        private
+
+        def secrets
+          @secrets ||= ::Rails.application.secrets.tap do |_|
+            # Reset secrets state if the app hasn't been initialized
+            # See https://github.com/palkan/anyway_config/issues/14
+            next if ::Rails.application.initialized?
+
+            # Address unable to load application: NameError: instance variable @secrets
+            # not defined
+            next unless ::Rails.application.instance_variable_defined?(:@secrets)
+
+            ::Rails.application.remove_instance_variable(:@secrets)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/.rbnext/3.1/anyway/config.rb

@@ -33,6 +33,7 @@ module Anyway # :nodoc:
       deconstruct_keys
       dig
       dup
+      format_unknown_attribute
       initialize
       load
       load_from_sources
@@ -52,6 +53,8 @@ module Anyway # :nodoc:
 
     class ValidationError < Error; end
 
+    class UnknownAttributesError < ValidationError; end
+
     include OptparseConfig
     include DynamicConfig
 
@@ -374,6 +377,8 @@ module Anyway # :nodoc:
         )
 
         if overrides
+          reject_unknown_config_attributes!(overrides, source: :overrides, strict: Settings.future.reject_unknown_overrides == true)
+
           Tracing.trace!(:load) { overrides }
 
           Utils.deep_merge!(base_config, overrides)
@@ -400,10 +405,16 @@ module Anyway # :nodoc:
     def load_from_sources(base_config, **opts)
       source_filter = self.class.configuration_sources
 
-      Anyway.loaders.each do |(id, loader)|
+      Anyway.loaders.each do |(id, loader_or_proc)|
         next if source_filter && !source_filter.include?(id)
-        Utils.deep_merge!(base_config, loader.call(**opts))
+
+        loader = (loader_or_proc.is_a?(Class) && loader_or_proc <= Loaders::Base) ? loader_or_proc.new(**opts) : loader_or_proc
+        loader_data = loader.call(**opts)
+        reject_unknown_config_attributes!(loader_data, source: id) if loader.is_a?(Loaders::Base) && loader.schemaful?
+
+        Utils.deep_merge!(base_config, loader_data)
       end
+
       base_config
     end
 
@@ -460,13 +471,50 @@ module Anyway # :nodoc:
 
       self.class.required_attributes.select do |name|
         val = values.dig(*name.to_s.split(".").map(&:to_sym))
-        val.nil? || (val.is_a?(String) && val.empty?)
+        val.nil? || (val.respond_to?(:to_s) && val.to_s.empty?)
       end.then do |missing|
         next if missing.empty?
         raise_validation_error "The following config parameters for `#{self.class.name}(config_name: #{self.class.config_name})` are missing or empty: #{missing.join(", ")}"
       end
     end
 
+    def reject_unknown_config_attributes!(data, source:, strict: false)
+      return if data.nil? || data.empty?
+
+      mode = strict || Settings.enforce_config_schema
+      return unless mode
+
+      known = self.class.config_attributes.map(&:to_s)
+      unknown = data.keys.map(&:to_s) - known
+
+      unless strict
+        rescuer = Settings.rescue_unknown_attributes_with
+        unknown.reject! { |it| rescuer.call(self, it) } if rescuer
+      end
+
+      return if unknown.empty?
+
+      msg = "Unknown config attributes for `#{self.class.name || "<anonymous>"}(config_name: #{config_name})` " \
+        "provided by #{source}: #{unknown.map { |it| format_unknown_attribute(it, known) }.join(", ")}"
+
+      if strict
+        raise ArgumentError, msg
+      elsif mode == :warn
+        Kernel.warn msg
+      else
+        raise UnknownAttributesError, msg
+      end
+    end
+
+    def format_unknown_attribute(key, known)
+      return key unless defined?(::DidYouMean::SpellChecker)
+
+      suggestions = ::DidYouMean::SpellChecker.new(dictionary: known).correct(key)
+      return key if suggestions.empty?
+
+      "#{key} (did you mean: #{suggestions.join(", ")}?)"
+    end
+
     def write_config_attr(key, val)
       key = key.to_sym
       return unless self.class.config_attributes.include?(key)

data/lib/.rbnext/3.1/anyway/loaders/base.rb

@@ -11,11 +11,15 @@ module Anyway
         end
       end
 
-      def initialize(local:)
+      def initialize(local: Anyway::Settings.use_local_files, **__kwrest__)
         @local = local
       end
 
       def use_local?() = @local == true
+
+      # Whether this loader supports strict schema (so we can warn or raise on
+      # unknown attributes)
+      def schemaful?() = false
     end
   end
 end