Class: Liteguard::Scope

Inherits:
Object
  • Object
show all
Defined in:
lib/liteguard/scope.rb

Overview

Immutable request scope for Liteguard evaluations.

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client, properties, bundle_key, protected_context) ⇒ void

Create a new immutable scope.

Application code typically uses ‘Liteguard::Client#create_scope` instead of calling this constructor directly.

Parameters:

  • client (Client) —

    owning client instance

  • properties (Hash{String => Object}) —

    normalized scope properties

  • bundle_key (String) —

    cache key for the bundle used by this scope

  • protected_context (ProtectedContext, nil) —

    optional signed protected context associated with the scope



18
19
20
21
22
23
24
25
26
27
28
 
# File 'lib/liteguard/scope.rb', line 18

def initialize(client, properties, bundle_key, protected_context)
  @client = client
  @properties = properties.dup.freeze
  @bundle_key = bundle_key
  @protected_context = protected_context ? ProtectedContext.new(
    properties: protected_context.properties.dup,
    signature: protected_context.signature.dup,
    issued_at: protected_context.issued_at,
    expires_at: protected_context.expires_at
  ) : nil
end

Instance Attribute Details

#bundle_key ⇒ String (readonly)

Returns cache key for the guard bundle backing this scope.

Returns:

  • (String) —

    cache key for the guard bundle backing this scope



5
6
7
 
# File 'lib/liteguard/scope.rb', line 5

def bundle_key
  @bundle_key
end

Instance Method Details

#add_properties(properties) ⇒ Scope

Alias-friendly wrapper for #with_properties.

Parameters:

  • properties (Hash) —

    properties to merge into the scope

Returns:

  • (Scope) —

    a derived immutable scope



44
45
46
 
# File 'lib/liteguard/scope.rb', line 44

def add_properties(properties)
  with_properties(properties)
end

#belongs_to?(client) ⇒ Boolean

Determine whether this scope belongs to the provided client.

Parameters:

  • client (Client) —

    client to compare against

Returns:

  • (Boolean) —

    ‘true` when both references point to the same client



175
176
177
 
# File 'lib/liteguard/scope.rb', line 175

def belongs_to?(client)
  @client.equal?(client)
end

#bind_protected_context(protected_context) ⇒ Scope

Return a new scope bound to a protected-context bundle.

Parameters:

Returns:

  • (Scope) —

    a derived immutable scope



69
70
71
 
# File 'lib/liteguard/scope.rb', line 69

def bind_protected_context(protected_context)
  @client.bind_protected_context_to_scope(self, protected_context)
end

#clear_properties(names) ⇒ Scope

Return a new scope with the named properties removed.

Parameters:

  • names (Array<String, Symbol>) —

    property names to remove

Returns:

  • (Scope) —

    a derived immutable scope



52
53
54
55
56
 
# File 'lib/liteguard/scope.rb', line 52

def clear_properties(names)
  next_properties = @properties.dup
  Array(names).each { |name| next_properties.delete(name.to_s) }
  self.class.new(@client, next_properties, @bundle_key, @protected_context)
end

#clear_protected_context ⇒ Scope

Return a new scope using the public guard bundle.

Returns:

  • (Scope) —

    a derived immutable scope without protected context



76
77
78
79
 
# File 'lib/liteguard/scope.rb', line 76

def clear_protected_context
  @client.ensure_public_bundle_ready
  self.class.new(@client, @properties, Client::PUBLIC_BUNDLE_KEY, nil)
end

#evaluate(name, options = nil, **legacy_options) ⇒ GuardDecision

Evaluate a guard and return a GuardDecision with full reasoning.

Like #is_open but returns the full decision context including the reason, matched rule index, and the merged properties used. A guard_check telemetry signal is buffered.

Parameters:

  • name (String) —

    guard name to evaluate

  • options (Hash, nil) (defaults to: nil) —

    optional per-call overrides

Returns:



119
120
121
 
# File 'lib/liteguard/scope.rb', line 119

def evaluate(name, options = nil, **legacy_options)
  @client.evaluate_in_scope(self, name, options, **legacy_options)
end

#execute_if_open(name, options = nil, **legacy_options) { ... } ⇒ Object?

Evaluate a guard and run the block only when it is open.

Parameters:

  • name (String) —

    guard name to evaluate

  • options (Hash, nil) (defaults to: nil) —

    optional per-call overrides

Yields:

  • Runs only when the guard resolves open

Returns:

  • (Object, nil) —

    the block return value, or ‘nil` when the guard is closed



106
107
108
 
# File 'lib/liteguard/scope.rb', line 106

def execute_if_open(name, options = nil, **legacy_options, &block)
  @client.execute_if_open_in_scope(self, name, options, **legacy_options, &block)
end

#is_open(name, options = nil, **legacy_options) ⇒ Boolean

Evaluate a guard within this scope and emit telemetry.

Parameters:

  • name (String) —

    guard name to evaluate

  • options (Hash, nil) (defaults to: nil) —

    optional per-call overrides

Returns:

  • (Boolean) —

    ‘true` when the guard resolves open



86
87
88
 
# File 'lib/liteguard/scope.rb', line 86

def is_open(name, options = nil, **legacy_options)
  @client.is_open_in_scope(self, name, options, **legacy_options)
end

#peek_is_open(name, options = nil, **legacy_options) ⇒ Boolean

Evaluate a guard within this scope without emitting telemetry.

Parameters:

  • name (String) —

    guard name to evaluate

  • options (Hash, nil) (defaults to: nil) —

    optional per-call overrides

Returns:

  • (Boolean) —

    ‘true` when the guard resolves open



95
96
97
 
# File 'lib/liteguard/scope.rb', line 95

def peek_is_open(name, options = nil, **legacy_options)
  @client.peek_is_open_in_scope(self, name, options, **legacy_options)
end

#properties ⇒ Hash

Return a defensive copy of the scope properties.

Returns:

  • (Hash) —

    scope properties keyed by string



153
154
155
 
# File 'lib/liteguard/scope.rb', line 153

def properties
  @properties.dup
end

#protected_context ⇒ ProtectedContext?

Return a defensive copy of the protected context, if present.

Returns:



160
161
162
163
164
165
166
167
168
169
 
# File 'lib/liteguard/scope.rb', line 160

def protected_context
  return nil unless @protected_context

  ProtectedContext.new(
    properties: @protected_context.properties.dup,
    signature: @protected_context.signature.dup,
    issued_at: @protected_context.issued_at,
    expires_at: @protected_context.expires_at
  )
end

#reset_properties ⇒ Scope

Return a new scope with all properties cleared.

Returns:

  • (Scope) —

    an empty derived scope



61
62
63
 
# File 'lib/liteguard/scope.rb', line 61

def reset_properties
  self.class.new(@client, {}, @bundle_key, @protected_context)
end

#run { ... } ⇒ Object

Bind this scope as the active scope for the duration of a block.

Yields:

  • Runs with this scope bound as active

Returns:

  • (Object) —

    the block return value



138
139
140
 
# File 'lib/liteguard/scope.rb', line 138

def run(&block)
  @client.with_scope(self, &block)
end

#start_execution ⇒ Execution

Start a new execution correlation context.

Returns a lightweight Execution handle that groups telemetry signals under a shared execution ID. Call Execution#end_execution when the logical execution boundary is complete.

Returns:



130
131
132
 
# File 'lib/liteguard/scope.rb', line 130

def start_execution
  @client.start_execution
end

#with_execution { ... } ⇒ Object

Run a block in this scope and attach a shared execution identifier.

Yields:

  • Runs inside this scope and a correlated execution scope

Returns:

  • (Object) —

    the block return value



146
147
148
 
# File 'lib/liteguard/scope.rb', line 146

def with_execution(&block)
  @client.with_scope(self) { @client.with_execution(&block) }
end

#with_properties(properties) ⇒ Scope

Return a new scope with merged properties.

Existing properties are preserved unless overwritten by the new values.

Parameters:

  • properties (Hash) —

    properties to merge into the scope

Returns:

  • (Scope) —

    a derived immutable scope



36
37
38
 
# File 'lib/liteguard/scope.rb', line 36

def with_properties(properties)
  self.class.new(@client, @properties.merge(normalize_properties(properties)), @bundle_key, @protected_context)
end