Module: Legion::Settings::Overlay

Defined in:
lib/legion/settings/overlay.rb

Overview

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.

Constant Summary collapse

THREAD_KEY = 
:legion_settings_overlay

Class Method Summary collapse

Class Method Details

.active? ⇒ Boolean

Returns true when a thread-local overlay is active.



46
47
48
 
# File 'lib/legion/settings/overlay.rb', line 46

def active?
  !Thread.current[THREAD_KEY].nil?
end

.clear_overlay! ⇒ Object

Clear the thread-local overlay for the current thread.



51
52
53
 
# File 'lib/legion/settings/overlay.rb', line 51

def clear_overlay!
  Thread.current[THREAD_KEY] = nil
end

.current_overlay ⇒ Hash?

Return the current thread-local overlay hash, or nil if none is active.



39
40
41
 
# File 'lib/legion/settings/overlay.rb', line 39

def current_overlay
  Thread.current[THREAD_KEY]
end

.overlay_for(key) ⇒ Object?

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.



61
62
63
64
65
66
67
68
 
# File 'lib/legion/settings/overlay.rb', line 61

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

.with_overlay(overrides) { ... } ⇒ Object

Execute a block with the given overrides active in the current thread. The overrides hash uses the same top-level key structure as Settings.

Yields:

  • block executed with the overlay active



28
29
30
31
32
33
34
 
# File 'lib/legion/settings/overlay.rb', line 28

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