legion-settings 1.3.24 → 1.3.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 482b26bda825959da123ce4b68f0503181bbc05a2af3bbbbc912d067e76ae2cb
-  data.tar.gz: 45c70811a101925a22ec51244b6f8e42e1ad9d8cacc02eb8374c56eb11b6a9da
+  metadata.gz: '028759fea7f4684e657e735676b17ebe147f71781e8bf3aac758fb226c8be81d'
+  data.tar.gz: 56d57df1ca491e5976c2f654701aad0d93fd8d3cf8347c4a4e2c9eb3a487941a
 SHA512:
-  metadata.gz: b063262f1a803400f2d86fbdbfe62d7778f9c2c8f01bd78baf73d74216b25417c4ae53791cacced67024bad384d4e3d3fab5239b729d568f636496f6a5b43170
-  data.tar.gz: b8d8c69b34ef0688e2d82b7ad88a175c59ee2dfb48f64267fa409ad26b29ae7394213f0947a6da73c07479f5df65390f75e15f602957eab031aeee14be261c59
+  metadata.gz: c75da04c00df4cd9db84c50c3327e9b5c80ad5a4137531cb1aad9d5e8efc8809736d97359c8de2c791aed1848e1b2b0c2948d27a50fee24ed3263e54de9d63ab
+  data.tar.gz: 51d80d06a89f8ccc4284d6ff90741e2f083f08827ecd8c6ab853d7ff913aad24780ac22e25b0999fcd9464544161b15f5983bd824ea62ac3cfce6ca4e3b1acd2

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Legion::Settings Changelog
 
+## [1.3.25] - 2026-03-31
+
+### Added
+- `Settings.with_overlay(overrides) { }` — thread-local request-scoped settings overlay for per-tenant LLM routing without node restarts; nestable, cleans up via ensure block (closes #9)
+- `Settings.load_project_env(start_dir:)` — discovers and loads `.legionio.env` from Dir.pwd upward; dot-notation keys (`llm.default_model=haiku`) map to nested settings paths; auto-called during `Settings.load` (closes #10)
+- `Legion::Settings::Overlay` module — thread-local overlay storage with `with_overlay`, `current_overlay`, `overlay_for`, `clear_overlay!`
+- `Legion::Settings::ProjectEnv` module — env file discovery, parsing, and merging
+- Resolution order: request overlay > project `.legionio.env` > global settings
+- 44 new specs covering overlay scoping/nesting/cleanup, thread isolation, `.legionio.env` parsing, discovery, key mapping, and resolution order
+
 ## [1.3.24] - 2026-03-30
 
 ### Added

data/Gemfile

@@ -10,5 +10,6 @@ group :test do
   gem 'rspec'
   gem 'rspec_junit_formatter'
   gem 'rubocop'
+  gem 'rubocop-legion'
   gem 'simplecov'
 end

data/lib/legion/settings/overlay.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Legion
+  module Settings
+    # Thread-local request-scoped settings overlay.
+    #
+    # Provides block-scoped overrides that sit above global settings in the
+    # resolution order: request overlay > project .legionio.env > global settings.
+    #
+    # Usage:
+    #   Legion::Settings.with_overlay(llm: { default_model: 'claude-3-haiku' }) do
+    #     Legion::Settings[:llm][:default_model]  # => 'claude-3-haiku'
+    #   end
+    #
+    # Overlays are nestable — inner overlay merges on top of the outer one.
+    module Overlay
+      THREAD_KEY = :legion_settings_overlay
+
+      class << self
+        # Execute a block with the given overrides active in the current thread.
+        # The overrides hash uses the same top-level key structure as Settings.
+        #
+        # @param overrides [Hash] settings to override for the duration of the block
+        # @yield block executed with the overlay active
+        # @return the return value of the block
+        def with_overlay(overrides)
+          previous = Thread.current[THREAD_KEY]
+          Thread.current[THREAD_KEY] = deep_merge(previous || {}, overrides)
+          yield
+        ensure
+          Thread.current[THREAD_KEY] = previous
+        end
+
+        # Return the current thread-local overlay hash, or nil if none is active.
+        #
+        # @return [Hash, nil]
+        def current_overlay
+          Thread.current[THREAD_KEY]
+        end
+
+        # Clear the thread-local overlay for the current thread.
+        def clear_overlay!
+          Thread.current[THREAD_KEY] = nil
+        end
+
+        # Resolve a top-level key against the active overlay, returning the
+        # overlay value (which may need to be merged with base) or nil when no
+        # overlay is set.
+        #
+        # @param key [Symbol, String]
+        # @return [Object, nil]
+        def overlay_for(key)
+          overlay = Thread.current[THREAD_KEY]
+          return nil unless overlay
+
+          sym_key = key.to_sym
+          str_key = key.to_s
+          overlay[sym_key] || overlay[str_key]
+        end
+
+        private
+
+        def deep_merge(base, overrides)
+          result = base.dup
+          overrides.each do |key, value|
+            existing = result[key]
+            result[key] = if existing.is_a?(Hash) && value.is_a?(Hash)
+                            deep_merge(existing, value)
+                          else
+                            value
+                          end
+          end
+          result
+        end
+      end
+    end
+  end
+end

data/lib/legion/settings/project_env.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Legion
+  module Settings
+    # Per-project `.legionio.env` config file loader.
+    #
+    # Walks up from Dir.pwd searching for a `.legionio.env` file.  When found,
+    # parses `KEY=VALUE` lines with dot-notation keys and merges them into the
+    # loader at a priority between global settings and the request overlay.
+    #
+    # File format:
+    #   # comment lines are ignored
+    #   llm.default_model=claude-sonnet-4-5-20241022
+    #   cache.driver=redis
+    #
+    # Keys use dot notation to address nested settings paths.
+    # Values are always strings; callers should coerce as needed.
+    #
+    # Resolution order (lowest → highest priority):
+    #   global settings < .legionio.env < request overlay (#9)
+    module ProjectEnv
+      ENV_FILENAME = '.legionio.env'
+
+      class << self
+        # Walk up from +start_dir+ (defaults to Dir.pwd) looking for
+        # `.legionio.env`.  Returns the first file found, or nil.
+        #
+        # @param start_dir [String, nil] directory to start the search from
+        # @return [String, nil] absolute path to the file, or nil
+        def find_project_env_file(start_dir: nil)
+          dir = File.expand_path(start_dir || Dir.pwd)
+          loop do
+            candidate = File.join(dir, ENV_FILENAME)
+            return candidate if File.file?(candidate) && File.readable?(candidate)
+
+            parent = File.dirname(dir)
+            break if parent == dir # filesystem root
+
+            dir = parent
+          end
+          nil
+        end
+
+        # Parse a `.legionio.env` file and return a nested hash of overrides.
+        #
+        # @param path [String] absolute path to the file
+        # @return [Hash] nested hash with symbol keys
+        def parse_env_file(path)
+          result = {}
+          File.readlines(path, chomp: true).each_with_index do |line, idx|
+            next if line.strip.empty?
+            next if line.strip.start_with?('#')
+
+            parts = line.split('=', 2)
+            unless parts.length == 2
+              log_warn("#{path}:#{idx + 1}: skipping malformed line (no '=' found)")
+              next
+            end
+
+            raw_key, value = parts
+            key_parts = raw_key.strip.split('.')
+            if key_parts.empty? || key_parts.any?(&:empty?)
+              log_warn("#{path}:#{idx + 1}: skipping invalid key '#{raw_key.strip}'")
+              next
+            end
+
+            set_nested(result, key_parts.map(&:to_sym), value.strip)
+          end
+          result
+        end
+
+        # Find and load the project env file into the given settings hash,
+        # merging overrides (env file values win over existing values).
+        #
+        # @param settings [Hash] the settings hash to merge into (mutated in place)
+        # @param start_dir [String, nil] directory to start searching from
+        # @return [String, nil] path to the loaded file, or nil if none found
+        def load_into(settings, start_dir: nil)
+          path = find_project_env_file(start_dir: start_dir)
+          return nil unless path
+
+          overrides = parse_env_file(path)
+          deep_merge_into!(settings, overrides)
+          log_debug("ProjectEnv: loaded #{path}")
+          path
+        end
+
+        private
+
+        def set_nested(hash, keys, value)
+          *parents, leaf = keys
+          target = parents.reduce(hash) do |h, k|
+            h[k] ||= {}
+            h[k]
+          end
+          target[leaf] = value
+        end
+
+        def deep_merge_into!(base, overrides)
+          overrides.each do |key, value|
+            if base[key].is_a?(Hash) && value.is_a?(Hash)
+              deep_merge_into!(base[key], value)
+            else
+              base[key] = value
+            end
+          end
+          base
+        end
+
+        def log_debug(message)
+          defined?(Legion::Logging) ? Legion::Logging.debug(message) : nil
+        end
+
+        def log_warn(message)
+          defined?(Legion::Logging) ? Legion::Logging.warn(message) : warn(message)
+        end
+      end
+    end
+  end
+end

data/lib/legion/settings/version.rb

@@ -2,6 +2,6 @@
 
 module Legion
   module Settings
-    VERSION = '1.3.24'
+    VERSION = '1.3.25'
   end
 end

data/lib/legion/settings.rb

@@ -7,6 +7,8 @@ require 'legion/settings/loader'
 require 'legion/settings/schema'
 require 'legion/settings/validation_error'
 require 'legion/settings/helper'
+require 'legion/settings/overlay'
+require 'legion/settings/project_env'
 
 module Legion
   module Settings
@@ -35,6 +37,7 @@ module Legion
         end
 
         @loaded = true if has_config
+        load_project_env
         logger.info("Settings loaded from #{@loader.loaded_files.size} files")
         @loader
       end
@@ -50,7 +53,15 @@ module Legion
       def [](key)
         logger.info('Legion::Settings was not loading, auto loading now!') if @loader.nil?
         ensure_loader
-        @loader[key]
+        overlay_val = Overlay.overlay_for(key)
+        base_val = @loader[key]
+        if overlay_val.is_a?(Hash) && base_val.is_a?(Hash)
+          deep_merge_for_overlay(base_val, overlay_val)
+        elsif !overlay_val.nil?
+          overlay_val
+        else
+          base_val
+        end
       rescue NoMethodError, TypeError => e
         Legion::Logging.debug("Legion::Settings#[] key=#{key} failed: #{e.message}") if defined?(Legion::Logging)
         nil
@@ -86,6 +97,28 @@ module Legion
         cross_validations << block
       end
 
+      # Execute a block with thread-local settings overrides active.
+      # Overlays are nestable — inner overlays merge on top of outer ones.
+      # Resolution order inside the block: overlay > project env > global settings.
+      #
+      # @param overrides [Hash] settings to override for the duration of the block
+      # @yield the block executed with the overlay active
+      # @return the return value of the block
+      def with_overlay(overrides, &)
+        Overlay.with_overlay(overrides, &)
+      end
+
+      # Load (or reload) the nearest `.legionio.env` file into the settings loader.
+      # Searches from Dir.pwd upward.  Env-file values take priority over global
+      # settings but are overridden by a request overlay (with_overlay).
+      #
+      # @param start_dir [String, nil] directory to start searching from (defaults to Dir.pwd)
+      # @return [String, nil] path to the loaded file, or nil if none found
+      def load_project_env(start_dir: nil)
+        ensure_loader
+        ProjectEnv.load_into(@loader.settings, start_dir: start_dir)
+      end
+
       def dev_mode?
         return true if ENV['LEGION_DEV'] == 'true'
 
@@ -143,6 +176,7 @@ module Legion
         @loaded = nil
         @schema = nil
         @cross_validations = nil
+        Overlay.clear_overlay!
       end
 
       def logger
@@ -160,6 +194,19 @@ module Legion
 
       private
 
+      def deep_merge_for_overlay(base, overlay)
+        result = base.dup
+        overlay.each do |key, value|
+          existing = result[key]
+          result[key] = if existing.is_a?(Hash) && value.is_a?(Hash)
+                          deep_merge_for_overlay(existing, value)
+                        else
+                          value
+                        end
+        end
+        result
+      end
+
       def ensure_loader
         return @loader if @loader
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: legion-settings
 version: !ruby/object:Gem::Version
-  version: 1.3.24
+  version: 1.3.25
 platform: ruby
 authors:
 - Esity
@@ -54,6 +54,8 @@ files:
 - lib/legion/settings/helper.rb
 - lib/legion/settings/loader.rb
 - lib/legion/settings/os.rb
+- lib/legion/settings/overlay.rb
+- lib/legion/settings/project_env.rb
 - lib/legion/settings/resolver.rb
 - lib/legion/settings/schema.rb
 - lib/legion/settings/validation_error.rb