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
 
# 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
  ) : 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



42
43
44
 
# File 'lib/liteguard/scope.rb', line 42

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



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

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



67
68
69
 
# File 'lib/liteguard/scope.rb', line 67

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



50
51
52
53
54
 
# File 'lib/liteguard/scope.rb', line 50

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



74
75
76
77
 
# File 'lib/liteguard/scope.rb', line 74

def clear_protected_context
  @client.ensure_public_bundle_ready
  self.class.new(@client, @properties, Client::PUBLIC_BUNDLE_KEY, nil)
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



104
105
106
 
# File 'lib/liteguard/scope.rb', line 104

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



84
85
86
 
# File 'lib/liteguard/scope.rb', line 84

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



93
94
95
 
# File 'lib/liteguard/scope.rb', line 93

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



127
128
129
 
# File 'lib/liteguard/scope.rb', line 127

def properties
  @properties.dup
end

#protected_context ⇒ ProtectedContext?

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

Returns:



134
135
136
137
138
139
140
141
 
# File 'lib/liteguard/scope.rb', line 134

def protected_context
  return nil unless @protected_context

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

#reset_properties ⇒ Scope

Return a new scope with all properties cleared.

Returns:

  • (Scope) —

    an empty derived scope



59
60
61
 
# File 'lib/liteguard/scope.rb', line 59

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



112
113
114
 
# File 'lib/liteguard/scope.rb', line 112

def run(&block)
  @client.with_scope(self, &block)
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



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

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



34
35
36
 
# File 'lib/liteguard/scope.rb', line 34

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