Class: Legion::LLM::RoutingContext

Inherits:
Object
  • Object
show all
Includes:
Legion::Logging::Helper
Defined in:
lib/legion/llm/routing_context.rb

Overview

Trusted per-logical-request routing context (SSOT v3 D15 / §7.1).

Carries one opaque 128-bit server-generated routing seed, immutable across the request's initial attempt, retries, streaming failover, and embedding batch restart. No API header, body field, query parameter, translated request field, provider response, or GAIA payload can set the seed — it is created only by build via SecureRandom, or injected by for_test for deterministic specs. A request that bypassed the builder or carries a malformed seed is an internal programming/protocol failure (Errors::InvalidRoutingContext, HTTP 500), never a client error.

Constant Summary collapse

SEED_FORMAT = 
/\A[0-9a-f]{32}\z/

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(routing_seed:) ⇒ RoutingContext

Returns a new instance of RoutingContext.



44
45
46
47
48
49
50
51
52
 
# File 'lib/legion/llm/routing_context.rb', line 44

def initialize(routing_seed:)
  seed = routing_seed.to_s.dup
  unless seed.match?(SEED_FORMAT)
    raise Legion::LLM::Errors::InvalidRoutingContext,
          'routing_seed must be exactly 32 lowercase hexadecimal characters'
  end
  @routing_seed = seed.freeze
  freeze
end

Instance Attribute Details

#routing_seed ⇒ Object (readonly)

Returns the value of attribute routing_seed.



42
43
44
 
# File 'lib/legion/llm/routing_context.rb', line 42

def routing_seed
  @routing_seed
end

Class Method Details

.build ⇒ Object

Production constructor: one fresh server-generated seed.



25
26
27
 
# File 'lib/legion/llm/routing_context.rb', line 25

def build
  new(routing_seed: SecureRandom.hex(16))
end

.for_test(routing_seed:) ⇒ Object

Deterministic test constructor. Raises outside RSpec so no production path can inject a fixed seed.



31
32
33
34
35
36
37
 
# File 'lib/legion/llm/routing_context.rb', line 31

def for_test(routing_seed:)
  unless defined?(::RSpec)
    raise Legion::LLM::Errors::InvalidRoutingContext,
          'RoutingContext.for_test is only available under RSpec'
  end
  new(routing_seed: routing_seed)
end