class LittleGhost::Invocation
Carry one application request into an agent run. An invocation keeps framework fields and application-specific context in one indifferent-key environment.
invocation = LittleGhost::Invocation.new( message: "Why is transfer 481 pending?", account_id: "account-1", metadata: {channel: "customer_support"} ) invocation.message.text # => "Why is transfer 481 pending?" invocation[:account_id] # => "account-1" invocation.account_id # => "account-1"
String and symbol keys address the same field. Known fields have named accessors, while unknown application fields remain available through hash access and dynamic readers or writers. message and every history entry are normalized to Message objects; deadline_at lazily parses ISO 8601 text.
Missing run, invocation, and session identifiers are generated when the object is built. Actor identity is never inferred: applications that use it for persistence or tenant isolation must pass a value established by their trusted authentication boundary. Invalid payloads, messages, keys, or deadlines raise InvocationError.
Public Class Methods
Source
# File lib/little_ghost/invocation.rb, line 49 def initialize(env = {}) invalid!("Invocation payload must be an object") unless env.is_a?(Hash) @env = env.to_h { |key, value| [normalize_key(key), duplicate_value(value)] } DEFAULTS.each { |key, default| @env[key] = default.call unless @env.key?(key) } self.history = history self.message = message initialize_identifiers! end
Copies env, normalizes known framework fields, and fills missing identifiers.
The payload must be a Hash and must contain a non-blank message.
Public Instance Methods
Source
# File lib/little_ghost/invocation.rb, line 161 def [](key) = env[normalize_key(key)]
Looks up key after normalizing it to a String.
Source
# File lib/little_ghost/invocation.rb, line 166 def []=(key, value) normalized = normalize_key(key) value = normalize_message(value) if normalized == "message" value = Array(value).map { |message| Message.coerce(message) }.freeze if normalized == "history" env[normalized] = value end
Stores value under a normalized String key.
The message and history fields are normalized before storage.
Source
# File lib/little_ghost/invocation.rb, line 110
The explicit actor identifier supplied by the application.
Source
# File lib/little_ghost/invocation.rb, line 155 ACCESSORS.each do |name| define_method(name) { self[name] } define_method(:"#{name}=") { |value| self[name] = value } unless %i[message history].include?(name) end
Replaces the application-established actor identifier.
Source
# File lib/little_ghost/invocation.rb, line 80
JSON-like state made available to the agent run.
Source
# File lib/little_ghost/invocation.rb, line 122
Replaces the JSON-like agent state.
Source
# File lib/little_ghost/invocation.rb, line 188 def deadline_at value = self[:deadline_at] return value if value.nil? || value.is_a?(Time) self[:deadline_at] = Time.iso8601(String(value)) rescue ArgumentError, TypeError invalid!("deadline_at must be a valid time") end
The request deadline as a Time, parsing ISO 8601 text on first access.
Source
# File lib/little_ghost/invocation.rb, line 198 def deadline_at=(value) self[:deadline_at] = value end
Replaces the deadline; parsing is deferred until deadline_at is read.
Source
# File lib/little_ghost/invocation.rb, line 177 def dig(key, *names) = env.dig(normalize_key(key), *names)
Traverses the environment from normalized key through names.
# File lib/little_ghost/invocation.rb, line 174 def fetch(key, *defaults, &block) = env.fetch(normalize_key(key), *defaults, &block)
Fetches key with the same default and block behavior as Hash#fetch.
# File lib/little_ghost/invocation.rb, line 67
Frozen, normalized Messages that precede the current message.
Source
# File lib/little_ghost/invocation.rb, line 208 def history=(value) self[:history] = value end
Replaces and freezes the normalized message history.
Source
# File lib/little_ghost/invocation.rb, line 98
The invocation identifier, defaulting to run_id.
# File lib/little_ghost/invocation.rb, line 140
Replaces the invocation identifier.
Source
# File lib/little_ghost/invocation.rb, line 180 def key?(key) = env.key?(normalize_key(key))
Whether the environment contains key after normalization.
# File lib/little_ghost/invocation.rb, line 61
The normalized current Message.
Source
# File lib/little_ghost/invocation.rb, line 203 def message=(value) self[:message] = value end
Replaces and normalizes the current message.
Source
# File lib/little_ghost/invocation.rb, line 86
Application metadata carried with the request.
Source
# File lib/little_ghost/invocation.rb, line 128
Replaces the application metadata.
Source
# File lib/little_ghost/invocation.rb, line 92
The caller-supplied or generated top-level run identifier.
Source
# File lib/little_ghost/invocation.rb, line 134
Replaces the top-level run identifier.
Source
# File lib/little_ghost/invocation.rb, line 104
The session identifier, defaulting to run_id.
Source
# File lib/little_ghost/invocation.rb, line 146
Replaces the session identifier used for persistence.
Source
# File lib/little_ghost/invocation.rb, line 74
Per-request model settings merged after profile defaults. Treat these as trusted application policy, not unchecked request or model input.
Source
# File lib/little_ghost/invocation.rb, line 116
Replaces the trusted request-scoped model settings.
Source
# File lib/little_ghost/invocation.rb, line 185 def to_h = duplicate_value(env)
Produces a mutable copy of the invocation environment.
Nested hashes, arrays, strings, and other duplicable values are copied.