legion-settings 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 295484b08142fb1f6411ac9fbcd7d8f2222070c9a24d365c32df967281dc7f99
-  data.tar.gz: 9c2edecfcd659f6646256444fac34769c4d909df8247dab6965bbd0533067c23
+  metadata.gz: b2fb957d328761484c232467b3f37dfea86359a31726a6f3910e2e02838e3977
+  data.tar.gz: f10dcf26575430c481b466ebf490e3331d2d1c8ba841b438ca15560c8554c965
 SHA512:
-  metadata.gz: 30905e3f6ebbd1195ad34cea678b187c0e05700d65ed2593dd9ad7d735e8f7db771f16cdc86ae87b99abf0887c3a8ddd3429a4ae1073ea65ba904fb894578d32
-  data.tar.gz: 81349d2d33e693b560b78842a4530eedd6aaf9a723785bb31a4783255b1bd0101e8089817f616a58f99ee3737b3f3fdecbfe5c9ec56a392f906b01ec3db45d70
+  metadata.gz: b69cabe6c5265040c40791eb9b0c9c284c42438b11b9c146113b57fa9dc6c87d4c28072a3ce569cf9a5f34d3151bac4adaf8ed0a923fd8cecbcf40b8aae6103c
+  data.tar.gz: cbeaf56feeaca1cb4a02fdf76cf501e82d5619d489228570ec0906033e437249e3d85e98db652072c73b145bb80162f66f206dc6e1b0c79266606b7e647bf922

data/.github/workflows/ci.yml

@@ -0,0 +1,16 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  ci:
+    uses: LegionIO/.github/.github/workflows/ci.yml@main
+
+  release:
+    needs: ci
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    uses: LegionIO/.github/.github/workflows/release.yml@main
+    secrets:
+      rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}

data/.rubocop.yml

@@ -1,18 +1,50 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  NewCops: enable
+  SuggestExtensions: false
+
 Layout/LineLength:
-  Max: 120
+  Max: 160
+
+Layout/SpaceAroundEqualsInParameterDefault:
+  EnforcedStyle: space
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
 Metrics/MethodLength:
-  Max: 30
+  Max: 50
+
 Metrics/ClassLength:
   Max: 1500
+
+Metrics/ModuleLength:
+  Max: 1500
+
 Metrics/BlockLength:
-  Max: 50
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 60
+
+Metrics/CyclomaticComplexity:
+  Max: 15
+
+Metrics/PerceivedComplexity:
+  Max: 17
+
 Style/Documentation:
   Enabled: false
-AllCops:
-  TargetRubyVersion: 2.6
-  NewCops: enable
-  SuggestExtensions: false
+
+Style/SymbolArray:
+  Enabled: true
+
 Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Naming/FileName:
   Enabled: false
-Gemspec/RequiredRubyVersion:
-  Enabled: false

data/CHANGELOG.md

@@ -1,4 +1,24 @@
 # 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
+- `role` key in default settings with `profile` and `extensions` fields for extension profile filtering
+
+## v1.2.1
+
+### Added
+- `dev_mode?` method — returns true when `LEGION_DEV=true` env var or `Settings[:dev]` is set
+- Dev mode soft validation: `validate!` warns instead of raising when dev mode is active
+- Warning output via `Legion::Logging.warn` (falls back to `$stderr` if logging unavailable)
+
 ## v1.2.0
-Moving from BitBucket to GitHub inside the Optum org. All git history is reset from this point on
+Moving from BitBucket to GitHub. All git history is reset from this point on

data/CLAUDE.md

@@ -0,0 +1,154 @@
+# legion-settings: Configuration Management for LegionIO
+
+**Repository Level 3 Documentation**
+- **Parent**: `/Users/miverso2/rubymine/legion/CLAUDE.md`
+
+## Purpose
+
+Hash-like configuration store for the LegionIO framework. Loads settings from JSON files, directories, and environment variables. Provides a unified `Legion::Settings[:key]` accessor used by all other Legion gems. Includes schema-based validation with type inference, enum constraints, and cross-module checks.
+
+**GitHub**: https://github.com/LegionIO/legion-settings
+**License**: Apache-2.0
+
+## Architecture
+
+```
+Legion::Settings (singleton module)
+├── .load(config_dir:, config_file:, config_dirs:)  # Initialize loader
+├── .[](:key)                                         # Hash-like accessor (auto-loads if needed)
+├── .set_prop(key, value)                             # Set a value
+├── .merge_settings(key, hash)                        # Merge module defaults + register schema
+├── .define_schema(key, overrides)                    # Add enum/required constraints
+├── .add_cross_validation(&block)                     # Register cross-module validation
+├── .validate!                                        # Run all validations, raise on errors
+├── .schema                                           # Access Schema instance
+├── .errors                                           # Access collected errors
+│
+├── Loader               # Core: loads env vars, files, directories, merges settings
+│   ├── .load_env        # Load environment variables (LEGION_API_PORT)
+│   ├── .load_file       # Load single JSON file
+│   ├── .load_directory  # Load all JSON files from directory
+│   ├── .load_module_settings    # Merge with module priority
+│   └── .load_module_default     # Merge with default priority
+│
+├── Schema               # Type inference, validation, unknown key detection
+│   ├── .register        # Infer types from defaults
+│   ├── .define_override # Add enum/required/type constraints
+│   ├── .validate_module # Validate values against schema
+│   └── .detect_unknown_keys  # Find typos via Levenshtein distance
+│
+├── ValidationError      # Collects all errors, raises once with formatted message
+├── OS                   # OS detection helpers
+└── CORE_MODULES         # [:transport, :cache, :crypt, :data, :logging, :client]
+```
+
+### Key Design Patterns
+
+- **Auto-Load on Access**: `Legion::Settings[:key]` auto-loads if not initialized
+- **Directory-Based Config**: Loads all `.json` files from config directories (default paths: `/etc/legionio`, `~/legionio`, `./settings`)
+- **Module Merging**: Each Legion module registers its defaults via `merge_settings` during startup
+- **Schema Inference**: Types are inferred from default values — no manual schema definitions needed
+- **Two-Pass Validation**: Per-module on merge (catches type mismatches immediately) + cross-module on `validate!` (catches dependency conflicts)
+- **Self-Service Registration**: LEX modules register schemas alongside defaults via `merge_settings` — no core changes needed
+- **Fail-Fast**: `validate!` collects all errors and raises `ValidationError` once with a formatted message
+- **Lazy Logging**: Falls back to `::Logger.new($stdout)` if `Legion::Logging` isn't loaded yet
+
+## Dependencies
+
+| Gem | Purpose |
+|-----|---------|
+| `legion-json` (>= 1.2) | JSON file parsing |
+
+## File Map
+
+| Path | Purpose |
+|------|---------|
+| `lib/legion/settings.rb` | Module entry, singleton accessors, schema integration, validation orchestration |
+| `lib/legion/settings/loader.rb` | Config loading from env/files/directories, deep merge, indifferent access |
+| `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 |
+| `spec/legion/loader_spec.rb` | Loader: env/file/directory loading tests |
+| `spec/legion/settings/schema_spec.rb` | Schema validation tests |
+| `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
+
+**Core configuration gem** - every other Legion gem reads its configuration from `Legion::Settings`. Settings are organized by module key:
+
+```ruby
+Legion::Settings[:transport]  # legion-transport config
+Legion::Settings[:cache]      # legion-cache config
+Legion::Settings[:crypt]      # legion-crypt config
+Legion::Settings[:data]       # legion-data config
+Legion::Settings[:client]     # Node identity (name, hostname, ready state)
+Legion::Settings[:role]       # Extension profile filtering (profile, extensions)
+```
+
+### Validation Usage
+
+```ruby
+# Modules register defaults (schema inferred automatically)
+Legion::Settings.merge_settings('transport', { host: 'localhost', port: 5672 })
+
+# Optional: add constraints beyond type inference
+Legion::Settings.define_schema('cache', { driver: { enum: %w[dalli redis] } })
+
+# Optional: cross-module validation
+Legion::Settings.add_cross_validation do |settings, errors|
+  if settings[:crypt][:cluster_secret].nil? && settings[:transport][:connected]
+    errors << { module: :crypt, path: 'crypt.cluster_secret', message: 'required when transport is connected' }
+  end
+end
+
+# Validate all at once (raises ValidationError with all collected errors)
+Legion::Settings.validate!
+```
+
+---
+
+**Maintained By**: Matthew Iverson (@Esity)

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec

data/LICENSE

@@ -186,7 +186,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2021 Optum
+   Copyright 2021 Esity
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

data/README.md

@@ -1,36 +1,57 @@
-Legion::Settings
-=====
+# legion-settings
 
-Legion::Settings is a hash like class used to store LegionIO Settings. 
+Configuration management module for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Loads settings from JSON files, directories, and environment variables. Provides a unified `Legion::Settings[:key]` accessor used by all other Legion gems.
 
-Supported Ruby versions and implementations
-------------------------------------------------
+## Installation
 
-Legion::Json should work identically on:
+```bash
+gem install legion-settings
+```
 
-* JRuby 9.2+
-* Ruby 2.4+
+Or add to your Gemfile:
 
+```ruby
+gem 'legion-settings'
+```
 
-Installation and Usage
-------------------------
+## Usage
 
-You can verify your installation using this piece of code:
+```ruby
+require 'legion/settings'
 
-```bash
-gem install legion-json
+Legion::Settings.load(config_dir: './')  # loads all .json files in the directory
+
+Legion::Settings[:client][:hostname]
+Legion::Settings[:transport][:connection][:host]
 ```
 
-```ruby
-require 'legion-settings'
-Legion::Settings.load(config_dir: './') # will automatically load json files it has access to inside this dir
+### Config Paths (checked in order)
 
-Legion::Settings[:client][:hostname]
-Legion::Settings[:client][:new_attribute] = 'foobar'
+1. `/etc/legionio/`
+2. `~/legionio/`
+3. `./settings/`
+
+Each Legion module registers its own defaults via `merge_settings` during startup.
+
+### Schema Validation
+
+Types are inferred automatically from default values. Optional constraints can be added:
 
+```ruby
+Legion::Settings.merge_settings('mymodule', { host: 'localhost', port: 8080 })
+Legion::Settings.define_schema('mymodule', { port: { required: true } })
+Legion::Settings.validate!  # raises ValidationError if any settings are invalid
+
+# In development, warn instead of raising:
+# Set LEGION_DEV=true or Legion::Settings.set_prop(:dev, true)
+# validate! will warn to $stderr (or Legion::Logging) instead of raising
 ```
 
-Authors
-----------
+## Requirements
+
+- Ruby >= 3.4
+- `legion-json`
+
+## License
 
-* [Matthew Iverson](https://github.com/Esity) - current maintainer
+Apache-2.0

data/legion-settings.gemspec

@@ -6,24 +6,24 @@ Gem::Specification.new do |spec|
   spec.name = 'legion-settings'
   spec.version       = Legion::Settings::VERSION
   spec.authors       = ['Esity']
-  spec.email         = %w[matthewdiverson@gmail.com ruby@optum.com]
+  spec.email         = ['matthewdiverson@gmail.com']
 
   spec.summary       = 'Legion::Settings'
   spec.description   = 'A gem written to handle LegionIO Settings in a consistent way across extensions'
-  spec.homepage      = 'https://github.com/Optum/legion-settings'
+  spec.homepage      = 'https://github.com/LegionIO/legion-settings'
   spec.license       = 'Apache-2.0'
   spec.require_paths = ['lib']
-  spec.required_ruby_version = '>= 2.4'
+  spec.required_ruby_version = '>= 3.4'
   spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.test_files        = spec.files.select { |p| p =~ %r{^test/.*_test.rb} }
-  spec.extra_rdoc_files  = %w[README.md LICENSE CHANGELOG.md]
+  spec.extra_rdoc_files = %w[README.md LICENSE CHANGELOG.md]
   spec.metadata = {
-    'bug_tracker_uri' => 'https://github.com/Optum/legion-settings/issues',
-    'changelog_uri' => 'https://github.com/Optum/legion-settings/src/main/CHANGELOG.md',
-    'documentation_uri' => 'https://github.com/Optum/legion-settings',
-    'homepage_uri' => 'https://github.com/Optum/LegionIO',
-    'source_code_uri' => 'https://github.com/Optum/legion-settings',
-    'wiki_uri' => 'https://github.com/Optum/legion-settings/wiki'
+    'bug_tracker_uri'       => 'https://github.com/LegionIO/legion-settings/issues',
+    'changelog_uri'         => 'https://github.com/LegionIO/legion-settings/blob/main/CHANGELOG.md',
+    'documentation_uri'     => 'https://github.com/LegionIO/legion-settings',
+    'homepage_uri'          => 'https://github.com/LegionIO/LegionIO',
+    'source_code_uri'       => 'https://github.com/LegionIO/legion-settings',
+    'wiki_uri'              => 'https://github.com/LegionIO/legion-settings/wiki',
+    'rubygems_mfa_required' => 'true'
   }
 
   spec.add_dependency 'legion-json', '>= 1.2'

data/lib/legion/settings/loader.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'socket'
 require 'legion/settings/os'
 
@@ -20,37 +22,38 @@ module Legion
       def client_defaults
         {
           hostname: system_hostname,
-          address: system_address,
-          name: "#{::Socket.gethostname.tr('.', '_')}.#{::Process.pid}",
-          ready: false
+          address:  system_address,
+          name:     "#{::Socket.gethostname.tr('.', '_')}.#{::Process.pid}",
+          ready:    false
         }
       end
 
       def default_settings
         {
-          client: client_defaults,
-          cluster: { public_keys: {} },
-          crypt: {
-            cluster_secret: nil,
+          client:                     client_defaults,
+          cluster:                    { public_keys: {} },
+          crypt:                      {
+            cluster_secret:         nil,
             cluster_secret_timeout: 5,
-            vault: { connected: false }
+            vault:                  { connected: false }
           },
-          cache: { enabled: true, connected: false, driver: 'dalli' },
-          extensions: {},
-          reload: false,
-          reloading: false,
-          auto_install_missing_lex: true,
+          cache:                      { enabled: true, connected: false, driver: 'dalli' },
+          extensions:                 {},
+          reload:                     false,
+          reloading:                  false,
+          auto_install_missing_lex:   true,
           default_extension_settings: {
             logger: { level: 'info', trace: false, extended: false }
           },
-          logging: {
-            level: 'info',
-            location: 'stdout',
-            trace: true,
+          logging:                    {
+            level:             'info',
+            location:          'stdout',
+            trace:             true,
             backtrace_logging: true
           },
-          transport: { connected: false },
-          data: { connected: false }
+          transport:                  { connected: false },
+          data:                       { connected: false },
+          role:                       { profile: nil, extensions: [] }
         }
       end
 
@@ -66,6 +69,11 @@ module Legion
         to_hash[key]
       end
 
+      def []=(key, value)
+        @settings[key] = value
+        @indifferent_access = false
+      end
+
       def hexdigest
         if @hexdigest && @indifferent_access
           @hexdigest
@@ -147,8 +155,9 @@ module Legion
       end
 
       def validate
-        validator = Validator.new
-        @errors += validator.run(@settings, legion_service_name)
+        Legion::Settings.validate!
+      rescue Legion::Settings::ValidationError
+        # errors are already collected in @errors
       end
 
       private
@@ -191,11 +200,12 @@ module Legion
       end
 
       def read_config_file(file)
-        contents = IO.read(file)
+        contents = File.read(file).dup
         if contents.respond_to?(:force_encoding)
           encoding = ::Encoding::ASCII_8BIT
           contents = contents.force_encoding(encoding)
-          contents.sub!("\xEF\xBB\xBF".force_encoding(encoding), '')
+          bom = (+"\xEF\xBB\xBF").force_encoding(encoding)
+          contents.sub!(bom, '')
         else
           contents.sub!(/^\357\273\277/, '')
         end
@@ -216,7 +226,6 @@ module Legion
         merged
       end
 
-      # rubocop:disable Metrics/AbcSize
       def deep_diff(hash_one, hash_two)
         keys = hash_one.keys.concat(hash_two.keys).uniq
         keys.each_with_object({}) do |key, diff|
@@ -229,15 +238,12 @@ module Legion
                       end
         end
       end
-      # rubocop:enable Metrics/AbcSize
 
       def create_loaded_tempfile!
         dir = ENV['LEGION_LOADED_TEMPFILE_DIR'] || Dir.tmpdir
         file_name = "legion_#{legion_service_name}_loaded_files"
         path = File.join(dir, file_name)
-        File.open(path, 'w') do |file|
-          file.write(@loaded_files.join(':'))
-        end
+        File.write(path, @loaded_files.join(':'))
         path
       end
 

data/lib/legion/settings/os.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Legion
   module Settings
     module OS
@@ -14,15 +16,10 @@ module Legion
       end
 
       def self.linux?
-        OS.unix? and !OS.mac?
-      end
-
-      def self.jruby?
-        RUBY_ENGINE == 'jruby'
+        OS.unix? && !OS.mac?
       end
 
       def os
-        return 'jruby' if jruby?
         return 'windows' if windows?
         return 'mac' if mac?
         return 'unix' if unix?