Class: Reeve::Context

Inherits:
Object
  • Object
show all
Defined in:
lib/reeve/context.rb

Overview

The per-invocation carrier: who is calling, on whose behalf, which tool, with what.

Created by an adapter or by the caller of the plain interface — never global, never reused between invocations. The principal is the only mutable field, because the envelope resolves it after the context exists, and clears it in an ensure.

Constant Summary collapse

UNKNOWN_AGENT_ID = 
"unknown"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(tool_name:, principal: nil, agent: nil, arguments: nil, metadata: nil, invoked_at: nil, invocation_id: nil) ⇒ Context

Returns a new instance of Context.



18
19
20
21
22
23
24
25
26
27
 
# File 'lib/reeve/context.rb', line 18

def initialize(tool_name:, principal: nil, agent: nil, arguments: nil, metadata: nil,
               invoked_at: nil, invocation_id: nil)
  @tool_name     = validate_tool_name(tool_name)
  @principal     = principal
  @agent         = build_agent(agent)
  @arguments     = symbolize(:arguments, arguments)
  @metadata      = symbolize(:metadata, metadata)
  @invoked_at    = invoked_at || Time.now
  @invocation_id = (invocation_id || SecureRandom.uuid).to_s
end

Instance Attribute Details

#agent ⇒ Object (readonly)

Returns the value of attribute agent.



15
16
17
 
# File 'lib/reeve/context.rb', line 15

def agent
  @agent
end

#arguments ⇒ Object (readonly)

Returns the value of attribute arguments.



15
16
17
 
# File 'lib/reeve/context.rb', line 15

def arguments
  @arguments
end

#invocation_id ⇒ Object (readonly)

Returns the value of attribute invocation_id.



15
16
17
 
# File 'lib/reeve/context.rb', line 15

def invocation_id
  @invocation_id
end

#invoked_at ⇒ Object (readonly)

Returns the value of attribute invoked_at.



15
16
17
 
# File 'lib/reeve/context.rb', line 15

def invoked_at
  @invoked_at
end

#metadata ⇒ Object (readonly)

Returns the value of attribute metadata.



15
16
17
 
# File 'lib/reeve/context.rb', line 15

def metadata
  @metadata
end

#principal ⇒ Object

Returns the value of attribute principal.



16
17
18
 
# File 'lib/reeve/context.rb', line 16

def principal
  @principal
end

#tool_name ⇒ Object (readonly)

Returns the value of attribute tool_name.



15
16
17
 
# File 'lib/reeve/context.rb', line 15

def tool_name
  @tool_name
end

Instance Method Details

#agent_id ⇒ Object 



49
50
51
 
# File 'lib/reeve/context.rb', line 49

def agent_id
  agent[:id]
end

#agent_name ⇒ Object 



53
54
55
 
# File 'lib/reeve/context.rb', line 53

def agent_name
  agent[:name]
end

#clear_principal! ⇒ Object

Called from the envelope's ensure block: nothing about one invocation may survive into the next on the same thread (data-model invariant 4).



35
36
37
 
# File 'lib/reeve/context.rb', line 35

def clear_principal!
  @principal = nil
end

#inspect ⇒ Object 



79
80
81
82
 
# File 'lib/reeve/context.rb', line 79

def inspect
  "#<Reeve::Context tool=#{tool_name.inspect} principal=#{principal_id.inspect} " \
    "agent=#{agent_id.inspect} invocation=#{invocation_id.inspect}>"
end

#principal_id ⇒ Object 



43
44
45
46
47
 
# File 'lib/reeve/context.rb', line 43

def principal_id
  return nil if principal.nil?

  principal.respond_to?(:id) ? principal.id.to_s : principal.to_s
end

#principal_resolved? ⇒ Boolean

Returns:

  • (Boolean) 


29
30
31
 
# File 'lib/reeve/context.rb', line 29

def principal_resolved?
  !principal.nil?
end

#principal_type ⇒ Object 



39
40
41
 
# File 'lib/reeve/context.rb', line 39

def principal_type
  principal&.class&.name
end

#to_h ⇒ Object

The audit-facing projection. The recorder adds the outcome, rule and records; everything here is known before the tool runs.

metadata belongs here even though nothing in the envelope reads it: the ledger has a column for it, the recorder maps it, and the contract check requires it — but this method used to omit it, so the column was written NULL on every call ever made. The transport detail a reviewer most wants after an incident (which request, which headers, which client) was accepted at the front door and dropped before the write.



65
66
67
68
69
70
71
72
73
74
75
76
77
 
# File 'lib/reeve/context.rb', line 65

def to_h
  {
    invocation_id: invocation_id,
    occurred_at: invoked_at,
    tool_name: tool_name,
    agent_id: agent_id,
    agent_name: agent_name,
    principal_type: principal_type,
    principal_id: principal_id,
    arguments: arguments,
    metadata: metadata
  }
end