liteguard 0.2.20260314

data/lib/liteguard/evaluation.rb

@@ -0,0 +1,104 @@
+module Liteguard
+  # Local rule evaluation engine — all evaluation is done without network calls.
+  module Evaluation
+    # Evaluate a guard against a property hash.
+    #
+    # Rules are processed in order and the first matching rule determines the
+    # result. If no enabled rule matches, the guard's configured default value
+    # is returned.
+    #
+    # @param guard [Guard] guard definition to evaluate
+    # @param properties [Hash{String => Object}] normalized evaluation properties
+    # @return [Boolean] the resolved open/closed result
+    def self.evaluate_guard(guard, properties)
+      guard.rules.each do |rule|
+        next unless rule.enabled
+        return rule.result if matches_rule?(rule, properties)
+      end
+      guard.default_value
+    end
+
+    # Determine whether a single rule matches the provided properties.
+    #
+    # @param rule [Rule] rule to evaluate
+    # @param props [Hash{String => Object}] normalized evaluation properties
+    # @return [Boolean] `true` when the rule matches
+    def self.matches_rule?(rule, props)
+      raw = props[rule.property_name]
+      return false if raw.nil?
+      return false if rule.values.empty?
+
+      first = rule.values.first
+
+      case rule.operator
+      when :equals     then values_equal?(raw, first)
+      when :not_equals then !values_equal?(raw, first)
+      when :in         then rule.values.any? { |v| values_equal?(raw, v) }
+      when :not_in     then rule.values.none? { |v| values_equal?(raw, v) }
+      when :regex
+        pattern = first.to_s
+        begin
+          !!(raw.to_s =~ Regexp.new(pattern))
+        rescue RegexpError
+          false
+        end
+      when :gt  then compare_ordered_values(raw, first)&.positive? || false
+      when :gte then (comparison = compare_ordered_values(raw, first)) && comparison >= 0 || false
+      when :lt  then compare_ordered_values(raw, first)&.negative? || false
+      when :lte then (comparison = compare_ordered_values(raw, first)) && comparison <= 0 || false
+      else false
+      end
+    end
+    private_class_method :matches_rule?
+
+    # Determine whether two raw property values are equal without mixed-type coercion.
+    #
+    # @param a [Object] left-hand value
+    # @param b [Object] right-hand value
+    # @return [Boolean] `true` when values are equal and of the same kind
+    def self.values_equal?(a, b)
+      case a
+      when TrueClass, FalseClass
+        b == a
+      when String
+        b.is_a?(String) && a == b
+      else
+        na = to_numeric(a)
+        nb = to_numeric(b)
+        !na.nil? && !nb.nil? && na == nb
+      end
+    end
+    private_class_method :values_equal?
+
+    # Compare ordered values without mixed-type coercion.
+    #
+    # @param a [Object] left-hand value
+    # @param b [Object] right-hand value
+    # @return [-1, 0, 1, nil] comparison result compatible with `<=>`
+    def self.compare_ordered_values(a, b)
+      if a.is_a?(String) || b.is_a?(String)
+        return nil unless a.is_a?(String) && b.is_a?(String)
+
+        return a <=> b
+      end
+
+      na = to_numeric(a)
+      nb = to_numeric(b)
+      return nil if na.nil? || nb.nil?
+
+      na <=> nb
+    end
+    private_class_method :compare_ordered_values
+
+    # Coerce supported numeric values into a comparable form.
+    #
+    # @param v [Object] raw property value
+    # @return [Float, nil] numeric representation, or `nil` if coercion fails
+    def self.to_numeric(v)
+      case v
+      when Numeric then v.to_f
+      end
+    end
+    private_class_method :to_numeric
+  end
+end

data/lib/liteguard/scope.rb

@@ -0,0 +1,159 @@
+module Liteguard
+  # Immutable request scope for Liteguard evaluations.
+  class Scope
+    # @return [String] cache key for the guard bundle backing this scope
+    attr_reader :bundle_key
+
+    # Create a new immutable scope.
+    #
+    # Application code typically uses `Liteguard::Client#create_scope` instead of
+    # calling this constructor directly.
+    #
+    # @param client [Client] owning client instance
+    # @param properties [Hash{String => Object}] normalized scope properties
+    # @param bundle_key [String] cache key for the bundle used by this scope
+    # @param protected_context [ProtectedContext, nil] optional signed protected
+    #   context associated with the scope
+    # @return [void]
+    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
+
+    # Return a new scope with merged properties.
+    #
+    # Existing properties are preserved unless overwritten by the new values.
+    #
+    # @param properties [Hash] properties to merge into the scope
+    # @return [Scope] a derived immutable scope
+    def with_properties(properties)
+      self.class.new(@client, @properties.merge(normalize_properties(properties)), @bundle_key, @protected_context)
+    end
+
+    # Alias-friendly wrapper for {#with_properties}.
+    #
+    # @param properties [Hash] properties to merge into the scope
+    # @return [Scope] a derived immutable scope
+    def add_properties(properties)
+      with_properties(properties)
+    end
+
+    # Return a new scope with the named properties removed.
+    #
+    # @param names [Array<String, Symbol>] property names to remove
+    # @return [Scope] a derived immutable scope
+    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
+
+    # Return a new scope with all properties cleared.
+    #
+    # @return [Scope] an empty derived scope
+    def reset_properties
+      self.class.new(@client, {}, @bundle_key, @protected_context)
+    end
+
+    # Return a new scope bound to a protected-context bundle.
+    #
+    # @param protected_context [ProtectedContext, Hash] signed protected context
+    # @return [Scope] a derived immutable scope
+    def bind_protected_context(protected_context)
+      @client.bind_protected_context_to_scope(self, protected_context)
+    end
+
+    # Return a new scope using the public guard bundle.
+    #
+    # @return [Scope] a derived immutable scope without protected context
+    def clear_protected_context
+      @client.ensure_public_bundle_ready
+      self.class.new(@client, @properties, Client::PUBLIC_BUNDLE_KEY, nil)
+    end
+
+    # Evaluate a guard within this scope and emit telemetry.
+    #
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [Boolean] `true` when the guard resolves open
+    def is_open(name, options = nil, **legacy_options)
+      @client.is_open_in_scope(self, name, options, **legacy_options)
+    end
+
+    # Evaluate a guard within this scope without emitting telemetry.
+    #
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @return [Boolean] `true` when the guard resolves open
+    def peek_is_open(name, options = nil, **legacy_options)
+      @client.peek_is_open_in_scope(self, name, options, **legacy_options)
+    end
+
+    # Evaluate a guard and run the block only when it is open.
+    #
+    # @param name [String] guard name to evaluate
+    # @param options [Hash, nil] optional per-call overrides
+    # @yield Runs only when the guard resolves open
+    # @return [Object, nil] the block return value, or `nil` when the guard is
+    #   closed
+    def execute_if_open(name, options = nil, **legacy_options, &block)
+      @client.execute_if_open_in_scope(self, name, options, **legacy_options, &block)
+    end
+
+    # Bind this scope as the active scope for the duration of a block.
+    #
+    # @yield Runs with this scope bound as active
+    # @return [Object] the block return value
+    def run(&block)
+      @client.with_scope(self, &block)
+    end
+
+    # Run a block in this scope and attach a shared execution identifier.
+    #
+    # @yield Runs inside this scope and a correlated execution scope
+    # @return [Object] the block return value
+    def with_execution(&block)
+      @client.with_scope(self) { @client.with_execution(&block) }
+    end
+
+    # Return a defensive copy of the scope properties.
+    #
+    # @return [Hash] scope properties keyed by string
+    def properties
+      @properties.dup
+    end
+
+    # Return a defensive copy of the protected context, if present.
+    #
+    # @return [ProtectedContext, nil] copied protected context or `nil`
+    def protected_context
+      return nil unless @protected_context
+
+      ProtectedContext.new(
+        properties: @protected_context.properties.dup,
+        signature: @protected_context.signature.dup
+      )
+    end
+
+    # Determine whether this scope belongs to the provided client.
+    #
+    # @param client [Client] client to compare against
+    # @return [Boolean] `true` when both references point to the same client
+    def belongs_to?(client)
+      @client.equal?(client)
+    end
+
+    private
+
+    def normalize_properties(properties)
+      return {} if properties.nil?
+
+      properties.each_with_object({}) { |(key, value), acc| acc[key.to_s] = value }
+    end
+  end
+end

data/lib/liteguard/types.rb

@@ -0,0 +1,134 @@
+# Code generated by tools/src/proto-codegen.ts — DO NOT EDIT.
+# Source of truth: proto/liteguard.proto  Run: make proto
+
+# Data-plane types — generated from proto/liteguard.proto.
+module Liteguard
+
+  OPERATORS = %i[equals not_equals in not_in regex gt gte lt lte].freeze
+
+  # A single rule condition within a Guard.
+  Rule = Data.define(
+    :property_name,
+    :operator,
+    :values,
+    :result,
+    :enabled
+  )
+
+  # A named feature guard with an ordered rule set.
+  Guard = Data.define(
+    :name,
+    :rules,
+    :default_value,
+    :adopted,
+    :rate_limit_per_minute,
+    :rate_limit_properties,
+    :disable_measurement
+  )
+
+  # Keys accepted by the options hash passed to {Liteguard::Client#is_open}.
+  CHECK_OPTION_KEYS = %i[properties fallback disable_measurement].freeze
+
+  # ProtectedContext (mirrors proto message).
+  ProtectedContext = Data.define(
+    :properties,
+    :signature
+  )
+
+  # GetGuardsRequest (mirrors proto message).
+  GetGuardsRequest = Data.define(
+    :project_client_key_id,
+    :environment,
+    :protected_context
+  )
+
+  # Parsed response from the guards endpoint.
+  GuardsResponse = Data.define(
+    :guards,
+    :refresh_rate_seconds,
+    :etag
+  )
+
+  # OpenTelemetry trace correlation attached to a Signal.
+  TraceContext = Data.define(
+    :trace_id,
+    :span_id,
+    :parent_span_id
+  )
+
+  # GuardCheckPerformance (mirrors proto message).
+  GuardCheckPerformance = Data.define(
+    :rss_bytes,
+    :heap_used_bytes,
+    :heap_total_bytes,
+    :cpu_time_ns,
+    :gc_count,
+    :thread_count
+  )
+
+  # GuardExecutionPerformance (mirrors proto message).
+  GuardExecutionPerformance = Data.define(
+    :duration_ns,
+    :rss_end_bytes,
+    :heap_used_end_bytes,
+    :heap_total_end_bytes,
+    :cpu_time_end_ns,
+    :gc_count_end,
+    :thread_count_end,
+    :completed,
+    :error_class
+  )
+
+  # SignalPerformance (mirrors proto message).
+  SignalPerformance = Data.define(
+    :guard_check,
+    :guard_execution
+  )
+
+  # A buffered guard-check record for upload to the data plane.
+  Signal = Data.define(
+    :guard_name,
+    :result,
+    :properties,
+    :timestamp_ms,
+    :trace,
+    :signal_id,
+    :execution_id,
+    :parent_signal_id,
+    :sequence_number,
+    :callsite_id,
+    :kind,
+    :dropped_signals_since_last,
+    :measurement
+  )
+
+  # SendUnadoptedGuardsRequest (mirrors proto message).
+  SendUnadoptedGuardsRequest = Data.define(
+    :project_client_key_id,
+    :environment,
+    :guard_names
+  )
+
+  # SendUnadoptedGuardsResponse (mirrors proto message).
+  SendUnadoptedGuardsResponse = Data.define(
+    :accepted
+  )
+
+  # Default values for {Liteguard::Client} initialization options.
+  CLIENT_OPTION_DEFAULTS = {
+    project_client_key_id:  nil,
+    environment:            nil,
+    fallback:               false,
+    refresh_rate_seconds:   30,
+    flush_rate_seconds:     10,
+    flush_size:             500,
+    backend_url:            "https://api.liteguard.io",
+    quiet:                  true,
+    http_timeout_seconds:   4,
+    flush_buffer_multiplier:4,
+    disable_measurement:    false,
+  }.freeze
+
+  CLIENT_OPTION_KEYS = CLIENT_OPTION_DEFAULTS.keys.freeze
+
+end

data/lib/liteguard.rb

@@ -0,0 +1,19 @@
+require_relative "liteguard/types"
+require_relative "liteguard/evaluation"
+require_relative "liteguard/scope"
+require_relative "liteguard/client"
+
+# Liteguard feature guard SDK for Ruby.
+#
+#   require 'liteguard'
+#
+#   client = Liteguard::Client.new('pckid-...', environment: 'production')
+#   client.start
+#   scope = client.create_scope(user_id: 'user-123', plan: 'pro')
+#
+#   if scope.is_open('payments.checkout')
+#     # feature is enabled
+#   end
+#
+module Liteguard
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: liteguard
+version: !ruby/object:Gem::Version
+  version: 0.2.20260314
+platform: ruby
+authors:
+- Liteguard
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+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.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/liteguard.rb
+- lib/liteguard/client.rb
+- lib/liteguard/evaluation.rb
+- lib/liteguard/scope.rb
+- lib/liteguard/types.rb
+homepage: https://liteguard.io
+licenses:
+- Apache-2.0
+metadata:
+  homepage_uri: https://liteguard.io
+  source_code_uri: https://github.com/liteguard/liteguard/tree/main/sdk/ruby
+  documentation_uri: https://github.com/liteguard/liteguard/tree/main/sdk/ruby#readme
+  changelog_uri: https://github.com/liteguard/liteguard/releases
+  bug_tracker_uri: https://github.com/liteguard/liteguard/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Feature guards, observability, and security response in a single import
+test_files: []