liteguard 0.4.20260317 → 0.6.20260405

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c5c689f405afe521506111a670b47b74494ed547562a8e083f1c040bcf5b283
-  data.tar.gz: a873c10263763a6700a3fb7ac1ea355d829c927a885cfbc048abf9221d66559a
+  metadata.gz: 64fb509c369cbd43217407216706597424220bd7143e03d460b3ad4428b4ff7a
+  data.tar.gz: b53c0c549c66353d3cb6f9aea811e5dffeb9e3b53f74f49a3cb315a17aa513e8
 SHA512:
-  metadata.gz: 36ffdc869fa486befba275c7a7683879b6ec0014071ba17d6339f28bf173980d4d8d6755f6c19d825b32f215f486cd62f9cbe64887bf1a4fe2c13ddc5401f763
-  data.tar.gz: 44cbf8a627c3edb19bbc1d0152d7670661279a728774dbf72def1e28329a6e6c8a7779b598eb37a23f12bf974bd956a4d778902af9b7d94e078b66efefeda12b
+  metadata.gz: 3488d12c50f5c9d3a6e48029ed450e2062f71efd24d06ebf217a88ee4742e0e3317c0731e4a2b13e38eebb33291bdc3b7745e8d5607451734c05a3378d58f383
+  data.tar.gz: e5a64bcf4c70b0692a88841666e1eb1358859073ac2d1d51fcae2a672ecf9e5dd6895b1524e1827e5a61995b6fbb4186621cf451ada5bf8cdd4410193ed7979e

data/README.md

@@ -47,16 +47,29 @@ client.shutdown
 - `client.start` fetches the initial bundle and starts refresh and flush workers.
 - `client.create_scope(**properties)` creates an immutable scope.
 - `scope.open?(name, **options)` evaluates locally.
+- `scope.evaluate(name, **options)` returns a `GuardDecision` with the full evaluation result.
 - `scope.execute_if_open(name, **options) { ... }` measures guarded work.
+- `scope.start_execution` creates an execution correlation handle.
 - `scope.bind_protected_context(**protected_context)` derives a protected scope.
+- `scope.properties` returns the current property bag for transport.
 - `client.flush` flushes buffered telemetry.
 - `client.shutdown` flushes and stops background work.
 
+## Convenience helpers
+
+For server applications that want request-scoped context propagation:
+
+- `client.with_scope(scope) { ... }` runs a block with `scope` as the active scope, isolated via `Thread.current`.
+- `client.active_scope` returns the scope bound to the current thread.
+- `client.with_properties(properties) { ... }` derives and activates a scope with additional properties.
+- `client.with_protected_context(protected_context) { ... }` derives and activates a protected scope.
+
 ## Notes
 
 - Evaluation is local after the initial bundle fetch.
 - Prefer explicit client and scope usage.
 - Unadopted guards default open and emit no signals.
+- The convenience helpers above also serve as infrastructure for auto-instrumentation of third-party dependencies. See the [Liteguard CLI](https://github.com/liteguard/liteguard/tree/main/cli) for build-time instrumentation.
 
 ## Development
 

data/lib/liteguard/client.rb

@@ -10,8 +10,8 @@ module Liteguard
   # This class is the primary Ruby SDK entrypoint.
   class Client
     DEFAULT_BACKEND_URL = "https://api.liteguard.io"
-    DEFAULT_REFRESH_RATE = 30
-    DEFAULT_FLUSH_RATE = 10
+    DEFAULT_REFRESH_RATE = 60
+    DEFAULT_FLUSH_RATE = 60
     DEFAULT_FLUSH_SIZE = 500
     DEFAULT_HTTP_TIMEOUT = 4
     DEFAULT_FLUSH_BUFFER_MULTIPLIER = 4
@@ -138,6 +138,25 @@ module Liteguard
       end
     end
 
+    # Start a new execution correlation context and return a handle.
+    #
+    # Returns a lightweight {Execution} handle that groups telemetry signals
+    # under a shared execution ID. Call {Execution#end_execution} when done.
+    # For block-based usage, prefer {#with_execution} instead.
+    #
+    # @return [Execution] a correlation handle
+    def start_execution
+      exec_id = next_signal_id
+      previous = Thread.current[:liteguard_execution_state]
+      Thread.current[:liteguard_execution_state] = {
+        execution_id: exec_id,
+        sequence_number: 0,
+        last_signal_id: nil,
+      }
+      cleanup = -> { Thread.current[:liteguard_execution_state] = previous }
+      Execution.new(exec_id, cleanup: cleanup)
+    end
+
     # ---------------------------------------------------------------------
     # Scope API
     # ---------------------------------------------------------------------
@@ -152,6 +171,13 @@ module Liteguard
 
     # Return the active scope for the current thread.
     #
+    # This method serves two roles:
+    # 1. Developer convenience for retrieving the current request scope.
+    # 2. Required infrastructure for auto-instrumentation. Instrumented
+    #    third-party code calls this method to discover the evaluation
+    #    context established by application-level middleware via
+    #    {#with_scope}.
+    #
     # @return [Scope] the active scope, or the default scope when none is bound
     def active_scope
       scope = Thread.current[@active_scope_key]
@@ -162,6 +188,13 @@ module Liteguard
 
     # Bind a scope for the duration of a block.
     #
+    # This method serves two roles:
+    # 1. Developer convenience for scoping guard evaluation to a request.
+    # 2. Required infrastructure for auto-instrumentation. When application
+    #    middleware activates a scope with this method, instrumented
+    #    third-party code running inside the block can discover the scope
+    #    via {#active_scope}.
+    #
     # @param scope [Scope, nil] scope to bind, or `nil` to reuse the current
     #   scope
     # @yield Runs with the resolved scope bound as active
@@ -209,64 +242,6 @@ module Liteguard
       with_scope(active_scope.bind_protected_context(protected_context)) { yield }
     end
 
-    # Replace the active scope with one that includes merged properties.
-    #
-    # @param properties [Hash] properties to merge into the active scope
-    # @return [Scope] the derived active scope
-    def add_properties(properties)
-      replace_current_scope(active_scope.with_properties(properties))
-    end
-
-    # Replace the active scope with one that omits the named properties.
-    #
-    # @param names [Array<String, Symbol>] property names to remove
-    # @return [Scope] the derived active scope
-    def clear_properties(names)
-      replace_current_scope(active_scope.clear_properties(Array(names).map(&:to_s)))
-    end
-
-    # Replace the active scope with an empty property scope.
-    #
-    # @return [Scope] the derived active scope
-    def reset_properties
-      replace_current_scope(active_scope.reset_properties)
-    end
-
-    # Replace the active scope with a protected-context-derived scope.
-    #
-    # @param protected_context [ProtectedContext, Hash] signed protected context
-    # @return [Scope] the derived active scope
-    def bind_protected_context(protected_context)
-      replace_current_scope(active_scope.bind_protected_context(protected_context))
-    end
-
-    # Replace the active scope with one using the public bundle.
-    #
-    # @return [Scope] the derived active scope
-    def clear_protected_context
-      replace_current_scope(active_scope.clear_protected_context)
-    end
-
-    # Return the current thread's evaluation properties.
-    #
-    # @return [Hash] active scope properties
-    def context
-      active_scope.properties
-    end
-
-    # Replace the current thread's active scope.
-    #
-    # Mutation helpers are intentionally thread-local so request-scoped data
-    # cannot leak through the process-wide default scope.
-    #
-    # @param scope [Scope] scope to install
-    # @return [Scope] the resolved scope
-    def replace_current_scope(scope)
-      resolved = resolve_scope(scope)
-      Thread.current[@active_scope_key] = resolved
-      resolved
-    end
-
     # Resolve a scope argument and verify that it belongs to this client.
     #
     # @param scope [Scope, nil] candidate scope
@@ -347,6 +322,74 @@ module Liteguard
       evaluate_guard_in_scope(scope, name.to_s, options, emit_signal: false)[:result]
     end
 
+    # Evaluate a guard and return a {GuardDecision} with full reasoning.
+    #
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [GuardDecision] the evaluation decision
+    def evaluate(name, options = nil, **legacy_options)
+      evaluate_in_scope(active_scope, name, options, **legacy_options)
+    end
+
+    # Evaluate a guard in the provided scope and return a {GuardDecision}.
+    #
+    # @param scope [Scope] scope to evaluate against
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [GuardDecision] the evaluation decision
+    def evaluate_in_scope(scope, name, options = nil, **legacy_options)
+      options = normalize_is_open_options(options, legacy_options)
+      resolved_scope = resolve_scope(scope)
+      bundle = bundle_for_scope(resolved_scope)
+      effective_fallback = options[:fallback].nil? ? @fallback : options[:fallback]
+
+      unless bundle.ready
+        return GuardDecision.new(
+          name: name.to_s, is_open: effective_fallback, adopted: false,
+          reason: "fallback", matched_rule_index: nil, properties: {}
+        )
+      end
+
+      guard = bundle.guards[name.to_s]
+      if guard.nil?
+        record_unadopted_guard(name.to_s)
+        return GuardDecision.new(
+          name: name.to_s, is_open: true, adopted: false,
+          reason: "unadopted", matched_rule_index: nil, properties: {}
+        )
+      end
+      unless guard.adopted
+        record_unadopted_guard(name.to_s)
+        return GuardDecision.new(
+          name: name.to_s, is_open: true, adopted: false,
+          reason: "unadopted", matched_rule_index: nil, properties: {}
+        )
+      end
+
+      props = resolved_scope.properties
+      props = props.merge(options[:properties]) if options[:properties]
+
+      detailed = Evaluation.evaluate_guard_detailed(guard, props)
+      result = detailed.result
+      if result && guard.rate_limit_per_minute.to_i > 0
+        result = check_rate_limit(name.to_s, guard.rate_limit_per_minute, guard.rate_limit_properties, props)
+      end
+
+      reason = detailed.matched_rule_index >= 0 ? "matched_rule" : "default_value"
+      matched_idx = detailed.matched_rule_index >= 0 ? detailed.matched_rule_index : nil
+
+      buffer_signal(
+        name.to_s, result, props,
+        kind: "guard_check",
+        measurement: measurement_enabled?(guard, options) ? capture_guard_check_measurement : nil
+      )
+
+      GuardDecision.new(
+        name: name.to_s, is_open: result, adopted: guard.adopted,
+        reason: reason, matched_rule_index: matched_idx, properties: props.dup
+      )
+    end
+
     # Evaluate a guard and execute the block only when it resolves open.
     #
     # @param name [String] guard name to evaluate

data/lib/liteguard/decision.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Liteguard
+  # Internal result from {Evaluation.evaluate_guard_detailed}.
+  DetailedEvalResult = Data.define(:result, :matched_rule_index)
+
+  # A lightweight execution correlation handle.
+  #
+  # Groups telemetry signals under a shared execution ID. Created by
+  # {Scope#start_execution} or {Client#start_execution}.
+  # Call {#end_execution} when the logical execution boundary is complete.
+  class Execution
+    # @return [String] the unique identifier for this execution
+    attr_reader :execution_id
+
+    # @api private
+    def initialize(execution_id, cleanup: nil)
+      @execution_id = execution_id
+      @cleanup = cleanup
+    end
+
+    # End this execution.
+    #
+    # After calling +end_execution+, subsequent guard checks will no longer be
+    # correlated with this execution.
+    # @return [void]
+    def end_execution
+      if @cleanup
+        @cleanup.call
+        @cleanup = nil
+      end
+    end
+  end
+end

data/lib/liteguard/evaluation.rb

@@ -18,6 +18,21 @@ module Liteguard
       guard.default_value
     end
 
+    # Evaluate a guard and return both the result and the matched rule index.
+    #
+    # @param guard [Guard] guard definition to evaluate
+    # @param properties [Hash{String => Object}] normalized evaluation properties
+    # @return [DetailedEvalResult] result with the matched rule index (-1 when default)
+    def self.evaluate_guard_detailed(guard, properties)
+      guard.rules.each_with_index do |rule, i|
+        next unless rule.enabled
+        if matches_rule?(rule, properties)
+          return DetailedEvalResult.new(result: rule.result, matched_rule_index: i)
+        end
+      end
+      DetailedEvalResult.new(result: guard.default_value, matched_rule_index: -1)
+    end
+
     # Determine whether a single rule matches the provided properties.
     #
     # @param rule [Rule] rule to evaluate

data/lib/liteguard/scope.rb

@@ -105,6 +105,30 @@ module Liteguard
       @client.execute_if_open_in_scope(self, name, options, **legacy_options, &block)
     end
 
+    # 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.
+    #
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [GuardDecision] the evaluation decision
+    def evaluate(name, options = nil, **legacy_options)
+      @client.evaluate_in_scope(self, name, options, **legacy_options)
+    end
+
+    # 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.
+    #
+    # @return [Execution] a correlation handle
+    def start_execution
+      @client.start_execution
+    end
+
     # Bind this scope as the active scope for the duration of a block.
     #
     # @yield Runs with this scope bound as active

data/lib/liteguard/types.rb

@@ -6,6 +6,8 @@ module Liteguard
 
   OPERATORS = %i[equals not_equals in not_in regex gt gte lt lte].freeze
 
+  GUARD_DECISION_REASONS = %i[matched_rule default_value unadopted fallback].freeze
+
   # A single rule condition within a Guard.
   Rule = Data.define(
     :property_name,
@@ -26,6 +28,16 @@ module Liteguard
     :disable_measurement
   )
 
+  # The detailed result of evaluating a guard.
+  GuardDecision = Data.define(
+    :name,
+    :is_open,
+    :adopted,
+    :reason,
+    :matched_rule_index,
+    :properties
+  )
+
   # Keys accepted by the options hash passed to {Liteguard::Client#is_open}.
   CHECK_OPTION_KEYS = %i[properties fallback disable_measurement].freeze
 
@@ -128,8 +140,8 @@ module Liteguard
     project_client_token:   nil,
     environment:            nil,
     fallback:               false,
-    refresh_rate_seconds:   30,
-    flush_rate_seconds:     10,
+    refresh_rate_seconds:   60,
+    flush_rate_seconds:     60,
     flush_size:             500,
     backend_url:            "https://api.liteguard.io",
     quiet:                  true,

data/lib/liteguard.rb

@@ -1,4 +1,5 @@
 require_relative "liteguard/types"
+require_relative "liteguard/decision"
 require_relative "liteguard/evaluation"
 require_relative "liteguard/scope"
 require_relative "liteguard/client"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: liteguard
 version: !ruby/object:Gem::Version
-  version: 0.4.20260317
+  version: 0.6.20260405
 platform: ruby
 authors:
 - Liteguard
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-18 00:00:00.000000000 Z
+date: 2026-04-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -50,6 +50,7 @@ files:
 - README.md
 - lib/liteguard.rb
 - lib/liteguard/client.rb
+- lib/liteguard/decision.rb
 - lib/liteguard/evaluation.rb
 - lib/liteguard/scope.rb
 - lib/liteguard/types.rb