liteguard 0.6.20260405 → 0.7.20260603

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64fb509c369cbd43217407216706597424220bd7143e03d460b3ad4428b4ff7a
-  data.tar.gz: b53c0c549c66353d3cb6f9aea811e5dffeb9e3b53f74f49a3cb315a17aa513e8
+  metadata.gz: 674b74c3afa87054d07083210c6f894afad8bc53cb2b6ae8a4e8bd045b30c14c
+  data.tar.gz: 6cf6d9d1fceb2760404e65a0b26faa05ff3687318492d4e124f35eced843e9f5
 SHA512:
-  metadata.gz: 3488d12c50f5c9d3a6e48029ed450e2062f71efd24d06ebf217a88ee4742e0e3317c0731e4a2b13e38eebb33291bdc3b7745e8d5607451734c05a3378d58f383
-  data.tar.gz: e5a64bcf4c70b0692a88841666e1eb1358859073ac2d1d51fcae2a672ecf9e5dd6895b1524e1827e5a61995b6fbb4186621cf451ada5bf8cdd4410193ed7979e
+  metadata.gz: 51eec265fceb91ea7994cf97d64878afb7312ce5bf72abe7732d584da009a8b7ce82efa163144110054254d01ad935cbe22a77ba3ca9f8a01ca5963f5d28d0ef
+  data.tar.gz: d998303a8c1bfa5156aabee64afe9d8b8e174c7da199004491b5cf5e94376a157644d459605fca2c2bbde7d87f9e1381993265f8d2fe0c636057acb60e4d4dc3

data/README.md

@@ -67,6 +67,7 @@ For server applications that want request-scoped context propagation:
 ## Notes
 
 - Evaluation is local after the initial bundle fetch.
+- Protected contexts use `properties`, `signature`, and optional `issued_at` / `expires_at` fields.
 - 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.

data/lib/liteguard/client.rb

@@ -370,10 +370,8 @@ module Liteguard
       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
+      applied_rate_limit = apply_rate_limit(guard, name.to_s, detailed.result, props, emit_signal: true)
+      result = applied_rate_limit[:result]
 
       reason = detailed.matched_rule_index >= 0 ? "matched_rule" : "default_value"
       matched_idx = detailed.matched_rule_index >= 0 ? detailed.matched_rule_index : nil
@@ -381,7 +379,8 @@ module Liteguard
       buffer_signal(
         name.to_s, result, props,
         kind: "guard_check",
-        measurement: measurement_enabled?(guard, options) ? capture_guard_check_measurement : nil
+        measurement: measurement_enabled?(guard, options) ? capture_guard_check_measurement : nil,
+        rate_limit_decisions: applied_rate_limit[:rate_limit_decisions]
       )
 
       GuardDecision.new(
@@ -475,14 +474,8 @@ module Liteguard
         props = props.merge(options[:properties])
       end
 
-      result = Evaluation.evaluate_guard(guard, props)
-      if result && guard.rate_limit_per_minute.to_i > 0
-        result = if emit_signal
-          check_rate_limit(name, guard.rate_limit_per_minute, guard.rate_limit_properties, props)
-        else
-          would_pass_rate_limit(name, guard.rate_limit_per_minute, guard.rate_limit_properties, props)
-        end
-      end
+      applied_rate_limit = apply_rate_limit(guard, name, Evaluation.evaluate_guard(guard, props), props, emit_signal: emit_signal)
+      result = applied_rate_limit[:result]
 
       signal = nil
       if emit_signal
@@ -491,7 +484,8 @@ module Liteguard
           result,
           props,
           kind: "guard_check",
-          measurement: measurement_enabled?(guard, options) ? capture_guard_check_measurement : nil
+          measurement: measurement_enabled?(guard, options) ? capture_guard_check_measurement : nil,
+          rate_limit_decisions: applied_rate_limit[:rate_limit_decisions]
         )
       end
 
@@ -533,6 +527,12 @@ module Liteguard
         projectClientToken: @project_client_token,
         environment: @environment,
         signals: batch.map do |signal|
+          rate_limit_decisions_payload = if signal.rate_limit_decisions&.any?
+            { rateLimitDecisions: signal.rate_limit_decisions.map { |decision| rate_limit_decision_payload(decision) } }
+          else
+            {}
+          end
+
           {
             guardName: signal.guard_name,
             result: signal.result,
@@ -545,7 +545,8 @@ module Liteguard
             kind: signal.kind,
             droppedSignalsSinceLast: signal.dropped_signals_since_last,
             **(signal.parent_signal_id ? { parentSignalId: signal.parent_signal_id } : {}),
-            **(signal.measurement ? { measurement: signal_measurement_payload(signal.measurement) } : {})
+            **(signal.measurement ? { measurement: signal_measurement_payload(signal.measurement) } : {}),
+            **rate_limit_decisions_payload
           }
         end
       )
@@ -598,7 +599,7 @@ module Liteguard
     # @param measurement [SignalPerformance, nil] optional measurement payload
     # @param parent_signal_id_override [String, nil] explicit parent signal ID
     # @return [Signal] buffered signal instance
-    def buffer_signal(guard_name, result, props, kind:, measurement: nil, parent_signal_id_override: nil)
+    def buffer_signal(guard_name, result, props, kind:, measurement: nil, parent_signal_id_override: nil, rate_limit_decisions: nil)
       metadata = next_signal_metadata(parent_signal_id_override)
       signal = Signal.new(
         guard_name: guard_name,
@@ -613,7 +614,8 @@ module Liteguard
         callsite_id: capture_callsite_id,
         kind: kind,
         dropped_signals_since_last: take_dropped_signals,
-        measurement: measurement
+        measurement: measurement,
+        rate_limit_decisions: Array(rate_limit_decisions).dup
       )
       should_flush = false
       @monitor.synchronize do
@@ -772,10 +774,13 @@ module Liteguard
       return PUBLIC_BUNDLE_KEY if protected_context.nil?
 
       keys = protected_context.properties.keys.sort
-      parts = [protected_context.signature, ""]
+      parts = [protected_context.signature, "properties"]
       keys.each do |key|
         parts << "#{key}=#{protected_context.properties[key]}"
       end
+      parts << ""
+      parts << "issuedAt=#{protected_context.issued_at || ''}"
+      parts << "expiresAt=#{protected_context.expires_at || ''}"
       parts.join("\x00")
     end
 
@@ -806,6 +811,8 @@ module Liteguard
           properties: protected_context.properties,
           signature: protected_context.signature
         }
+        payload[:protectedContext][:issuedAt] = protected_context.issued_at unless protected_context.issued_at.nil?
+        payload[:protectedContext][:expiresAt] = protected_context.expires_at unless protected_context.expires_at.nil?
       end
 
       uri = URI("#{@backend_url}/api/v1/guards")
@@ -942,12 +949,31 @@ module Liteguard
         rules: (raw["rules"] || []).map { |rule| parse_rule(rule) },
         default_value: !!raw["defaultValue"],
         adopted: !!raw["adopted"],
-        rate_limit_per_minute: (raw["rateLimitPerMinute"] || 0).to_i,
-        rate_limit_properties: Array(raw["rateLimitProperties"]),
+        rate_limit: parse_rate_limit(raw["rateLimit"]),
+        dry_run_rate_limit: parse_dry_run_rate_limit(raw["dryRunRateLimit"]),
         disable_measurement: raw.key?("disableMeasurement") ? raw["disableMeasurement"] : nil
       )
     end
 
+    def parse_rate_limit(raw)
+      return nil unless raw.is_a?(Hash)
+
+      GuardRateLimitConfig.new(
+        requests_per_minute: (raw["requestsPerMinute"] || 0).to_i,
+        partition_properties: Array(raw["partitionProperties"])
+      )
+    end
+
+    def parse_dry_run_rate_limit(raw)
+      return nil unless raw.is_a?(Hash)
+
+      GuardDryRunRateLimit.new(
+        dry_run_id: raw["dryRunId"].to_s,
+        requests_per_minute: (raw["requestsPerMinute"] || 0).to_i,
+        partition_properties: Array(raw["partitionProperties"])
+      )
+    end
+
     # Parse a rule payload returned by the backend.
     #
     # @param raw [Hash] decoded rule payload
@@ -970,19 +996,118 @@ module Liteguard
     #   the bucket key
     # @param props [Hash] evaluation properties
     # @return [Boolean] `true` when the evaluation is within the limit
-    def check_rate_limit(name, limit_per_minute, rate_limit_properties, props)
+    def evaluate_rate_limit(slot_key, limit_per_minute, rate_limit_properties, props, consume:)
       now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      key = rate_limit_bucket_key(name, rate_limit_properties, props)
+      key = rate_limit_bucket_key(slot_key, rate_limit_properties, props)
       @monitor.synchronize do
         entry = @rate_limit_state[key] || { window_start: now, count: 0 }
         entry = { window_start: now, count: 0 } if now - entry[:window_start] >= 60.0
-        if entry[:count] >= limit_per_minute
+        count_in_window = entry[:count] + 1
+        allowed = entry[:count] < limit_per_minute
+        if consume
+          entry = { window_start: entry[:window_start], count: count_in_window } if allowed
           @rate_limit_state[key] = entry
-          return false
         end
-        @rate_limit_state[key] = { window_start: entry[:window_start], count: entry[:count] + 1 }
+        { allowed: allowed, count_in_window: count_in_window }
       end
-      true
+    end
+
+    def consume_rate_limit(name, evaluation_target, dry_run_id, limit_per_minute, rate_limit_properties, props)
+      evaluate_rate_limit(
+        rate_limit_slot_key(name, evaluation_target, dry_run_id),
+        limit_per_minute,
+        rate_limit_properties,
+        props,
+        consume: true
+      )
+    end
+
+    def peek_rate_limit(name, evaluation_target, dry_run_id, limit_per_minute, rate_limit_properties, props)
+      evaluate_rate_limit(
+        rate_limit_slot_key(name, evaluation_target, dry_run_id),
+        limit_per_minute,
+        rate_limit_properties,
+        props,
+        consume: false
+      )
+    end
+
+    def rate_limit_slot_key(name, evaluation_target, dry_run_id)
+      return "#{name}\x00active" if evaluation_target == :active
+
+      "#{name}\x00dry_run=#{dry_run_id}"
+    end
+
+    def partition_values(rate_limit_properties, props)
+      Array(rate_limit_properties).each_with_object({}) do |property, values|
+        values[property] = props[property] if props.key?(property)
+      end
+    end
+
+    def build_rate_limit_decision(evaluation_target, dry_run_id, outcome, requests_per_minute, rate_limit_properties, props, count_in_window)
+      RateLimitDecision.new(
+        evaluation_target: evaluation_target,
+        dry_run_id: dry_run_id,
+        outcome: outcome,
+        requests_per_minute: requests_per_minute,
+        partition_properties: Array(rate_limit_properties).dup,
+        partition_values: partition_values(rate_limit_properties, props),
+        count_in_window: count_in_window
+      )
+    end
+
+    def apply_rate_limit(guard, name, initial_result, props, emit_signal:)
+      rate_limit_decisions = []
+      return { result: initial_result, rate_limit_decisions: rate_limit_decisions } unless initial_result
+
+      result = initial_result
+      rate_limit = guard.rate_limit
+      if rate_limit && rate_limit.requests_per_minute.to_i > 0
+        evaluation = if emit_signal
+          consume_rate_limit(name, :active, nil, rate_limit.requests_per_minute, rate_limit.partition_properties, props)
+        else
+          peek_rate_limit(name, :active, nil, rate_limit.requests_per_minute, rate_limit.partition_properties, props)
+        end
+        result = evaluation[:allowed]
+        if emit_signal
+          rate_limit_decisions << build_rate_limit_decision(
+            :active,
+            nil,
+            evaluation[:allowed] ? :within_limit : :limited,
+            rate_limit.requests_per_minute,
+            rate_limit.partition_properties,
+            props,
+            evaluation[:count_in_window]
+          )
+        end
+      end
+
+      dry_run_rate_limit = guard.dry_run_rate_limit
+      if emit_signal && dry_run_rate_limit && dry_run_rate_limit.requests_per_minute.to_i > 0
+        evaluation = consume_rate_limit(
+          name,
+          :dry_run,
+          dry_run_rate_limit.dry_run_id,
+          dry_run_rate_limit.requests_per_minute,
+          dry_run_rate_limit.partition_properties,
+          props
+        )
+        rate_limit_decisions << build_rate_limit_decision(
+          :dry_run,
+          dry_run_rate_limit.dry_run_id,
+          evaluation[:allowed] ? :within_limit : :would_limit,
+          dry_run_rate_limit.requests_per_minute,
+          dry_run_rate_limit.partition_properties,
+          props,
+          evaluation[:count_in_window]
+        )
+      end
+
+      { result: result, rate_limit_decisions: rate_limit_decisions }
+    end
+
+    def check_rate_limit(name, limit_per_minute, rate_limit_properties, props)
+      consume_rate_limit(name, :active, nil, limit_per_minute, rate_limit_properties, props)[:allowed]
     end
 
     # Check whether an evaluation would pass rate limiting without consuming a
@@ -995,15 +1120,7 @@ module Liteguard
     # @param props [Hash] evaluation properties
     # @return [Boolean] `true` when the evaluation would pass the limit
     def would_pass_rate_limit(name, limit_per_minute, rate_limit_properties, props)
-      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
-      key = rate_limit_bucket_key(name, rate_limit_properties, props)
-      @monitor.synchronize do
-        entry = @rate_limit_state[key]
-        return true if entry.nil?
-        return true if now - entry[:window_start] >= 60.0
-
-        entry[:count] < limit_per_minute
-      end
+      peek_rate_limit(name, :active, nil, limit_per_minute, rate_limit_properties, props)[:allowed]
     end
 
     # Build the cache key used for rate-limit buckets.
@@ -1066,19 +1183,51 @@ module Liteguard
       properties.each_with_object({}) { |(key, value), acc| acc[key.to_s] = value }
     end
 
+    # Normalize protected-context property keys and values to strings.
+    #
+    # @param properties [Hash, nil] raw protected property hash
+    # @return [Hash] normalized protected property hash
+    def normalize_protected_context_properties(properties)
+      return {} if properties.nil?
+
+      properties.each_with_object({}) { |(key, value), acc| acc[key.to_s] = value.to_s }
+    end
+
+    # Normalize an optional integer field from symbol or string keyed hashes.
+    #
+    # @param raw [Hash] source payload
+    # @param snake_key [Symbol] snake_case key
+    # @param camel_key [String] camelCase key
+    # @return [Integer, nil] normalized integer value
+    def normalize_optional_integer(raw, snake_key, camel_key)
+      value = raw[snake_key] || raw[camel_key]
+      return nil if value.nil?
+
+      Integer(value)
+    end
+
     # Normalize a protected-context payload into a `ProtectedContext` object.
     #
     # @param protected_context [ProtectedContext, Hash] raw protected context
     # @return [ProtectedContext] normalized protected context
     def normalize_protected_context(protected_context)
       raw = if protected_context.is_a?(ProtectedContext)
-        { properties: protected_context.properties, signature: protected_context.signature }
+        {
+          properties: protected_context.properties,
+          signature: protected_context.signature,
+          issued_at: protected_context.issued_at,
+          expires_at: protected_context.expires_at
+        }
       else
         protected_context
       end
       ProtectedContext.new(
-        properties: normalize_properties(raw[:properties] || raw["properties"] || {}),
-        signature: (raw[:signature] || raw["signature"]).to_s
+        properties: normalize_protected_context_properties(
+          raw[:properties] || raw["properties"] || {}
+        ),
+        signature: (raw[:signature] || raw["signature"]).to_s,
+        issued_at: normalize_optional_integer(raw, :issued_at, "issuedAt"),
+        expires_at: normalize_optional_integer(raw, :expires_at, "expiresAt")
       )
     end
 
@@ -1091,7 +1240,9 @@ module Liteguard
 
       ProtectedContext.new(
         properties: protected_context.properties.dup,
-        signature: protected_context.signature.dup
+        signature: protected_context.signature.dup,
+        issued_at: protected_context.issued_at,
+        expires_at: protected_context.expires_at
       )
     end
 
@@ -1216,6 +1367,18 @@ module Liteguard
       payload
     end
 
+    def rate_limit_decision_payload(decision)
+      {
+        evaluationTarget: decision.evaluation_target.to_s,
+        **(decision.dry_run_id ? { dryRunId: decision.dry_run_id } : {}),
+        outcome: decision.outcome.to_s,
+        requestsPerMinute: decision.requests_per_minute,
+        partitionProperties: decision.partition_properties,
+        partitionValues: decision.partition_values,
+        countInWindow: decision.count_in_window,
+      }
+    end
+
     # Track an unadopted guard so it can be reported with observation metadata.
     #
     # @param name [String] guard name to record

data/lib/liteguard/scope.rb

@@ -21,7 +21,9 @@ module Liteguard
       @bundle_key = bundle_key
       @protected_context = protected_context ? ProtectedContext.new(
         properties: protected_context.properties.dup,
-        signature: protected_context.signature.dup
+        signature: protected_context.signature.dup,
+        issued_at: protected_context.issued_at,
+        expires_at: protected_context.expires_at
       ) : nil
     end
 
@@ -160,7 +162,9 @@ module Liteguard
 
       ProtectedContext.new(
         properties: @protected_context.properties.dup,
-        signature: @protected_context.signature.dup
+        signature: @protected_context.signature.dup,
+        issued_at: @protected_context.issued_at,
+        expires_at: @protected_context.expires_at
       )
     end
 

data/lib/liteguard/types.rb

@@ -8,6 +8,10 @@ module Liteguard
 
   GUARD_DECISION_REASONS = %i[matched_rule default_value unadopted fallback].freeze
 
+  RATE_LIMIT_EVALUATION_TARGETS = %i[active dry_run].freeze
+
+  RATE_LIMIT_DECISION_OUTCOMES = %i[within_limit limited would_limit].freeze
+
   # A single rule condition within a Guard.
   Rule = Data.define(
     :property_name,
@@ -17,14 +21,27 @@ module Liteguard
     :enabled
   )
 
+  # GuardRateLimitConfig (mirrors proto message).
+  GuardRateLimitConfig = Data.define(
+    :requests_per_minute,
+    :partition_properties
+  )
+
+  # GuardDryRunRateLimit (mirrors proto message).
+  GuardDryRunRateLimit = Data.define(
+    :dry_run_id,
+    :requests_per_minute,
+    :partition_properties
+  )
+
   # A named feature guard with an ordered rule set.
   Guard = Data.define(
     :name,
     :rules,
     :default_value,
     :adopted,
-    :rate_limit_per_minute,
-    :rate_limit_properties,
+    :rate_limit,
+    :dry_run_rate_limit,
     :disable_measurement
   )
 
@@ -44,7 +61,9 @@ module Liteguard
   # ProtectedContext (mirrors proto message).
   ProtectedContext = Data.define(
     :properties,
-    :signature
+    :signature,
+    :issued_at,
+    :expires_at
   )
 
   # GetGuardsRequest (mirrors proto message).
@@ -57,6 +76,7 @@ module Liteguard
   # Parsed response from the guards endpoint.
   GuardsResponse = Data.define(
     :guards,
+    :omitted_protected_property_names,
     :refresh_rate_seconds,
     :etag
   )
@@ -97,6 +117,17 @@ module Liteguard
     :guard_execution
   )
 
+  # RateLimitDecision (mirrors proto message).
+  RateLimitDecision = Data.define(
+    :evaluation_target,
+    :dry_run_id,
+    :outcome,
+    :requests_per_minute,
+    :partition_properties,
+    :partition_values,
+    :count_in_window
+  )
+
   # A buffered guard-check record for upload to the data plane.
   Signal = Data.define(
     :guard_name,
@@ -111,7 +142,8 @@ module Liteguard
     :callsite_id,
     :kind,
     :dropped_signals_since_last,
-    :measurement
+    :measurement,
+    :rate_limit_decisions
   )
 
   # UnadoptedGuardObservation (mirrors proto message).

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: liteguard
 version: !ruby/object:Gem::Version
-  version: 0.6.20260405
+  version: 0.7.20260603
 platform: ruby
 authors:
 - Liteguard
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-06 00:00:00.000000000 Z
+date: 2026-06-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.13'
+        version: 3.13.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.13'
+        version: 3.13.2
 - !ruby/object:Gem::Dependency
   name: webmock
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.23'
+        version: 3.26.2
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.23'
+        version: 3.26.2
 description: Liteguard gives you feature guards, observability, and CVE auto-disable
   in one gem. Guards are evaluated entirely in-process against rules fetched once
   at startup. Every open? check is sub-millisecond with no network round-trip.