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.

Returns:

  • (Boolean) 


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.

Returns:

  • (Hash, nil) 


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.

Parameters:

  • key (Symbol, String)

Returns:

  • (Object, nil) 


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.

Parameters:

  • overrides (Hash) —

    settings to override for the duration of the block

Yields:

  • block executed with the overlay active

Returns:

  • the return value of the block



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