legion-settings 1.2.2 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e6bfc5465268327a07174136c9b4cc7eb8793345bc43b61bbefbf99fdf2406a
-  data.tar.gz: 9e6b1384a02334a6aecbe50474f184bfb7996d16efe36d9b80744a4feb6171bc
+  metadata.gz: b2fb957d328761484c232467b3f37dfea86359a31726a6f3910e2e02838e3977
+  data.tar.gz: f10dcf26575430c481b466ebf490e3331d2d1c8ba841b438ca15560c8554c965
 SHA512:
-  metadata.gz: c8d084a1a0b75578ada3bb4f765bf7948ed9f9969e03717d10bf357d82895d1717b7e634e5f7ce8385bc3f1f4734e7e8e0d00a24ad4596a04f72f950c1ec84ec
-  data.tar.gz: 6f2ed8e7febb6d6a9f9e36b3d86a5522230f7254bf46aaa4e966c9d60b91f71f80a8a2e46de9510f77bedbda53d759426d087c71fdecbb15c2ef2c1efdb08298
+  metadata.gz: b69cabe6c5265040c40791eb9b0c9c284c42438b11b9c146113b57fa9dc6c87d4c28072a3ce569cf9a5f34d3151bac4adaf8ed0a923fd8cecbcf40b8aae6103c
+  data.tar.gz: cbeaf56feeaca1cb4a02fdf76cf501e82d5619d489228570ec0906033e437249e3d85e98db652072c73b145bb80162f66f206dc6e1b0c79266606b7e647bf922

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Legion::Settings Changelog
 
+## [1.3.0] - 2026-03-16
+
+### Added
+- Universal secret resolver: `vault://` and `env://` URI references in any settings value
+- Fallback chain support via arrays (first non-nil wins)
+- `Legion::Settings.resolve_secrets!` method for explicit resolution phase
+- Vault read caching within a single resolution pass
+
 ## [1.2.2] - 2026-03-16
 
 ### Added

data/CLAUDE.md

@@ -68,6 +68,7 @@ Legion::Settings (singleton module)
 | `lib/legion/settings/schema.rb` | Type inference, validation logic, unknown key detection (Levenshtein) |
 | `lib/legion/settings/validation_error.rb` | Error collection and formatted reporting |
 | `lib/legion/settings/os.rb` | OS detection helpers |
+| `lib/legion/settings/resolver.rb` | Secret resolution: `vault://` and `env://` URI references, fallback chains |
 | `lib/legion/settings/version.rb` | VERSION constant |
 | `spec/legion/settings_spec.rb` | Core settings module tests |
 | `spec/legion/settings_module_spec.rb` | Module-level accessor and merge tests |
@@ -76,6 +77,44 @@ Legion::Settings (singleton module)
 | `spec/legion/settings/validation_error_spec.rb` | Error formatting tests |
 | `spec/legion/settings/integration_spec.rb` | End-to-end validation tests |
 | `spec/legion/settings/role_defaults_spec.rb` | Role profile default settings tests |
+| `spec/legion/settings/resolver_spec.rb` | Secret resolver tests (env://, vault://, fallback chains) |
+
+## Secret Resolution
+
+Settings values can reference external secret sources using URI syntax. Resolved in-place via `Legion::Settings.resolve_secrets!` (called automatically after `Legion::Crypt.start` in the boot sequence).
+
+### URI Schemes
+
+| Scheme | Format | Resolution |
+|--------|--------|------------|
+| `vault://` | `vault://path/to/secret#key` | `Legion::Crypt.read(path)[key]` |
+| `env://` | `env://ENV_VAR_NAME` | `ENV['ENV_VAR_NAME']` |
+| *(plain string)* | `"guest"` | Returned as-is |
+
+### Fallback Chains
+
+Array values are tried in order — first non-nil wins:
+
+```json
+{
+  "transport": {
+    "connection": {
+      "password": ["vault://secret/data/rabbitmq#password", "env://RABBITMQ_PASSWORD", "guest"]
+    }
+  }
+}
+```
+
+### Logging Strategy
+
+- Vault not connected + vault refs exist: one summary warning with count
+- Individual vault path failures: debug level
+- Entire chain resolves to nil: one warning per key path
+- Success: info summary with resolved counts
+
+### Implementation
+
+`Legion::Settings::Resolver` module with `module_function`. Called via `Legion::Settings.resolve_secrets!` which delegates to `Resolver.resolve_secrets!(@loader.to_hash)`. Vault reads are cached by path within a single resolution pass.
 
 ## Role in LegionIO
 

data/lib/legion/settings/resolver.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Legion
+  module Settings
+    module Resolver
+      VAULT_PATTERN = %r{\Avault://(.+?)#(.+)\z}
+      ENV_PATTERN   = %r{\Aenv://(.+)\z}
+      URI_PATTERN   = %r{\A(?:vault|env)://}
+
+      module_function
+
+      def resolve_secrets!(settings_hash)
+        return settings_hash unless settings_hash.is_a?(Hash)
+
+        @vault_available = vault_connected?
+        @vault_cache     = {}
+
+        vault_count = count_vault_refs(settings_hash)
+        log_warn("Vault not connected — #{vault_count} vault:// reference(s) will not be resolved") if vault_count.positive? && !@vault_available
+
+        resolved = 0
+        unresolved = 0
+        walk(settings_hash, path: '') do |result|
+          if result == :resolved
+            resolved += 1
+          elsif result == :unresolved
+            unresolved += 1
+          end
+        end
+
+        log_info("Settings resolver: #{resolved} resolved, #{unresolved} unresolved") if resolved.positive? || unresolved.positive?
+
+        settings_hash
+      end
+
+      def resolve_value(value)
+        case value
+        when String
+          return value unless value.match?(URI_PATTERN)
+
+          resolve_single(value)
+        when Array
+          return value unless resolvable_chain?(value)
+
+          resolve_chain(value)
+        else
+          value
+        end
+      end
+
+      def resolve_single(str)
+        if (m = str.match(VAULT_PATTERN))
+          resolve_vault(m[1], m[2])
+        elsif (m = str.match(ENV_PATTERN))
+          ENV.fetch(m[1], nil)
+        else
+          str
+        end
+      end
+
+      def resolve_chain(arr)
+        arr.each do |entry|
+          result = if entry.is_a?(String) && entry.match?(URI_PATTERN)
+                     resolve_single(entry)
+                   else
+                     entry
+                   end
+          return result unless result.nil?
+        end
+        nil
+      end
+
+      def has_vault_refs?(hash) # rubocop:disable Naming/PredicatePrefix
+        count_vault_refs(hash).positive?
+      end
+
+      def count_vault_refs(hash)
+        return 0 unless hash.is_a?(Hash)
+
+        hash.sum do |_key, value|
+          case value
+          when String then value.match?(VAULT_PATTERN) ? 1 : 0
+          when Array  then value.count { |v| v.is_a?(String) && v.match?(VAULT_PATTERN) }
+          when Hash   then count_vault_refs(value)
+          else 0
+          end
+        end
+      end
+
+      def vault_connected?
+        return false unless defined?(Legion::Crypt)
+        return false unless defined?(Legion::Settings)
+
+        Legion::Settings[:crypt][:vault][:connected] == true
+      rescue StandardError
+        false
+      end
+
+      def walk(hash, path:, &block)
+        hash.each do |key, value|
+          current_path = path.empty? ? key.to_s : "#{path}.#{key}"
+
+          case value
+          when Hash
+            walk(value, path: current_path, &block)
+          when String
+            next unless value.match?(URI_PATTERN)
+
+            resolved = resolve_single(value)
+            if resolved.nil?
+              log_warn("Settings resolver: could not resolve #{current_path} (#{value})")
+              block&.call(:unresolved)
+            else
+              hash[key] = resolved
+              block&.call(:resolved)
+            end
+          when Array
+            next unless resolvable_chain?(value)
+
+            resolved = resolve_chain(value)
+            if resolved.nil?
+              log_warn("Settings resolver: fallback chain exhausted for #{current_path}")
+              block&.call(:unresolved)
+            else
+              hash[key] = resolved
+              block&.call(:resolved)
+            end
+          end
+        end
+      end
+
+      def resolve_vault(path, key)
+        return nil unless @vault_available
+
+        @vault_cache[path] ||= begin
+          Legion::Crypt.read(path)
+        rescue StandardError => e
+          log_debug("Settings resolver: vault read failed for #{path}: #{e.message}")
+          nil
+        end
+
+        data = @vault_cache[path]
+        return nil unless data.is_a?(Hash)
+
+        data[key.to_sym] || data[key.to_s]
+      end
+
+      def resolvable_chain?(arr)
+        arr.any? { |v| v.is_a?(String) && v.match?(URI_PATTERN) }
+      end
+
+      def log_info(message)
+        if defined?(Legion::Logging)
+          Legion::Logging.info(message)
+        else
+          $stdout.puts(message)
+        end
+      end
+
+      def log_warn(message)
+        if defined?(Legion::Logging)
+          Legion::Logging.warn(message)
+        else
+          warn(message)
+        end
+      end
+
+      def log_debug(message)
+        if defined?(Legion::Logging)
+          Legion::Logging.debug(message)
+        else
+          $stdout.puts(message)
+        end
+      end
+    end
+  end
+end

data/lib/legion/settings/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Settings
-    VERSION = '1.2.2'
+    VERSION = '1.3.0'
   end
 end

data/lib/legion/settings.rb

@@ -79,6 +79,12 @@ module Legion
         warn_validation_errors(errors)
       end
 
+      def resolve_secrets!
+        @loader = load if @loader.nil?
+        require 'legion/settings/resolver'
+        Resolver.resolve_secrets!(@loader.to_hash)
+      end
+
       def schema
         @schema ||= Schema.new
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-settings
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.3.0
 platform: ruby
 authors:
 - Esity
@@ -46,6 +46,7 @@ files:
 - lib/legion/settings.rb
 - lib/legion/settings/loader.rb
 - lib/legion/settings/os.rb
+- lib/legion/settings/resolver.rb
 - lib/legion/settings/schema.rb
 - lib/legion/settings/validation_error.rb
 - lib/legion/settings/version.rb