toggly 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e803470a2b9ba974d853c9b93a9da9404467f701c76ed6fbb0bd678627da7112
-  data.tar.gz: 86c792820f5ddecf1c951118bafa9d8df632299e919d8c48165e2c80e13b4b9b
+  metadata.gz: 750edb3f8314278562443c8e2d1c55342f0cf412660c67be6518b73adb7e391c
+  data.tar.gz: 37e1959bfe363ca29d389c511663f170bac4d8501f3ae5343dcde76a43ced889
 SHA512:
-  metadata.gz: fae2c7e8f07c7e88050e459ebfe2762895ae4fcebb73aced9f03985a5a12c5f01e73cecfd1943352610ac08a50eb8e8d57553203f59c99a7fcf781a80fe01a92
-  data.tar.gz: 7bbe9e747d3aa3dcde62701bb26ccd3541184b68274e8da59d49fed6d515db3c6e3e9e63e964e28bed254c35d7e0ddefa130fc865a8886843a56e4b65b5b53c9
+  metadata.gz: 0ffa45e64fd2517b201de7701c74f0e797bdfbeddc76affc469fe37113e352b99a6024db42c36e9ce13d163f3530e6cc23a17bf770eeedd9f2c22dc3216c30b5
+  data.tar.gz: 4cf489e30d206a5bf9bd92153b865e57ebaf04190909c16559d10e90edfd1a017ef27bed38c6356186102167cf0617111f0f34a950443fb3ce32b50c69d3cb9a

data/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-08-21
+
+### Added
+
+- ContextProperty entity filters (`context_kind` / `context_requirement_type`) with operators eq, neq, gt, gte, lt, lte, in, contains. Fail closed. User filters AND entity filters; percentage stays user-only.
+- `Toggly::EntityContext`, `Toggly.register_context`, and optional startup PUT `sdk/{appKey}/contexts` (`disable_entity_context_registration` to opt out).
+
 ## [0.1.0] - 2024-XX-XX
 
 ### Added

data/README.md

@@ -4,6 +4,8 @@ Core Ruby SDK for [Toggly](https://toggly.io) feature flag management.
 
 **Zero dependencies** - pure Ruby implementation.
 
+Entity `ContextProperty` filters evaluate `Toggly::EntityContext` (`kind`, `key`, `attributes`) and are ANDed with user filters. `Toggly.register_context` optionally PUTs schemas to `sdk/{appKey}/contexts`.
+
 ## Installation
 
 ```ruby

data/lib/toggly/client.rb

@@ -52,6 +52,7 @@ module Toggly
       @refresh_thread = nil
 
       initialize_definitions
+      Toggly.register_entity_contexts_at_startup(@config) unless @config.disable_entity_context_registration
       start_background_refresh unless @config.disable_background_refresh
     end
 

data/lib/toggly/config.rb

@@ -35,6 +35,7 @@ module Toggly
 
     # @return [Boolean] Enable WebSocket live updates (default: true)
     attr_accessor :enable_live_updates
+    attr_accessor :disable_entity_context_registration
 
     # @return [String] Application version
     attr_accessor :app_version
@@ -73,6 +74,7 @@ module Toggly
       @enable_undefined_in_dev = options[:enable_undefined_in_dev] || false
       @disable_background_refresh = options[:disable_background_refresh] || false
       @enable_live_updates = options.fetch(:enable_live_updates, true)
+      @disable_entity_context_registration = options.fetch(:disable_entity_context_registration, false)
       @app_version = options[:app_version]
       @instance_name = options[:instance_name]
       @defaults = options[:defaults] || {}

data/lib/toggly/context.rb

@@ -11,18 +11,14 @@ module Toggly
   #   )
   class Context
     # @return [String, nil] User identity for percentage rollouts and targeting
-    attr_reader :identity
+    # identity, groups, traits, and optional entity for ContextProperty filters
+    attr_reader :identity, :groups, :traits, :entity
 
-    # @return [Array<String>] Groups the user belongs to
-    attr_reader :groups
-
-    # @return [Hash<String, Object>] Custom traits for contextual targeting
-    attr_reader :traits
-
-    def initialize(identity: nil, groups: [], traits: {})
+    def initialize(identity: nil, groups: [], traits: {}, entity: nil)
       @identity = identity&.to_s
       @groups = Array(groups).map(&:to_s)
       @traits = normalize_traits(traits)
+      @entity = entity
     end
 
     # Create a context with just an identity
@@ -80,7 +76,8 @@ module Toggly
       Context.new(
         identity: @identity,
         groups: @groups,
-        traits: @traits.merge(normalize_traits(new_traits))
+        traits: @traits.merge(normalize_traits(new_traits)),
+        entity: @entity
       )
     end
 
@@ -92,7 +89,8 @@ module Toggly
       Context.new(
         identity: @identity,
         groups: @groups + new_groups.flatten.map(&:to_s),
-        traits: @traits
+        traits: @traits,
+        entity: @entity
       )
     end
 

data/lib/toggly/definitions_provider.rb

@@ -217,7 +217,12 @@ module Toggly
       base = @config.definitions_url || @config.base_url
       ws_url = base.gsub(%r{^https://}, "wss://").gsub(%r{^http://}, "ws://")
       ws_url = ws_url.chomp("/")
-      "#{ws_url}/#{@config.app_key}/ws"
+      params = {
+        "sdk" => "ruby",
+        "sdkVersion" => Toggly::VERSION
+      }
+      params["rev"] = @etag if @etag && !@etag.empty?
+      "#{ws_url}/#{@config.app_key}/ws?#{URI.encode_www_form(params)}"
     end
 
     def connect_websocket

data/lib/toggly/entity_context.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+# Entity context registry, mappers, and startup catalog PUT.
+module Toggly
+  EntityContext = Struct.new(:kind, :key, :attributes, keyword_init: true) do
+    def attribute(name)
+      return nil unless attributes.is_a?(Hash)
+
+      return attributes[name] if attributes.key?(name)
+      return attributes[name.to_s] if attributes.key?(name.to_s)
+
+      attributes.each { |k, v| return v if k.to_s.casecmp?(name.to_s) }
+      nil
+    end
+
+    def attribute?(name)
+      return false unless attributes.is_a?(Hash)
+
+      attributes.key?(name) || attributes.key?(name.to_s) ||
+        attributes.keys.any? { |k| k.to_s.casecmp?(name.to_s) }
+    end
+  end
+
+  EntityContextPropertySchema = Struct.new(:name, :type, keyword_init: true)
+  EntityContextSchemaRegistration = Struct.new(:kind, :key_property, :display_name, :properties, keyword_init: true)
+
+  @entity_mappers = {}
+  @entity_schemas = {}
+  @entity_mutex = Mutex.new
+
+  class << self
+    def register_context(kind, schema: nil, &mapper)
+      @entity_mutex.synchronize do
+        @entity_mappers[kind] = mapper if mapper
+        if schema
+          schema.kind = kind
+          schema.display_name ||= kind
+          @entity_schemas[kind] = schema
+        end
+      end
+    end
+
+    def map_entity(kind, entity)
+      mapper = @entity_mutex.synchronize { @entity_mappers[kind] }
+      return nil unless mapper
+
+      mapper.call(entity)
+    end
+
+    def entity_schemas
+      @entity_mutex.synchronize { @entity_schemas.values.dup }
+    end
+
+    def clear_entity_context_registrations
+      @entity_mutex.synchronize do
+        @entity_mappers.clear
+        @entity_schemas.clear
+      end
+    end
+
+    def register_entity_contexts_at_startup(config)
+      return if config.respond_to?(:disable_entity_context_registration) && config.disable_entity_context_registration
+      return if config.app_key.nil? || config.app_key.empty?
+
+      regs = entity_schemas
+      return if regs.empty?
+
+      payload = {
+        contexts: regs.map do |r|
+          {
+            kind: r.kind,
+            keyProperty: r.key_property,
+            displayName: r.display_name || r.kind,
+            properties: Array(r.properties).map { |p| { name: p.name, type: p.type } }
+          }
+        end
+      }
+      uri = URI.join(config.base_url.end_with?("/") ? config.base_url : "#{config.base_url}/", "sdk/#{config.app_key}/contexts")
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = config.http_timeout || 10
+      http.read_timeout = config.http_timeout || 10
+      req = Net::HTTP::Put.new(uri)
+      req["Content-Type"] = "application/json"
+      req.body = JSON.generate(payload)
+      http.request(req)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/toggly/evaluation_engine.rb

@@ -69,8 +69,53 @@ module Toggly
     private
 
     def evaluate_rules(definition, context, result = nil)
-      definition.rules.each_with_index do |rule, index|
-        rule_type = rule["type"] || rule[:type] || "always_on"
+      entity_rules, user_rules = definition.rules.partition { |rule| Evaluators::ContextProperty.context_property?(rule) }
+
+      if entity_rules.any?
+        entity_ok = evaluate_entity_group(definition, entity_rules, context)
+        unless entity_ok
+          result&.reason = "entity_filters_failed"
+          return false
+        end
+        return true if user_rules.empty?
+
+        return evaluate_filter_group(user_rules, definition.requirement_type, context, definition.feature_key, result)
+      end
+
+      sequential_rules(user_rules.empty? ? definition.rules : user_rules, definition, context, result)
+    end
+
+    def evaluate_entity_group(definition, rules, context)
+      entity = context&.entity
+      return false unless entity
+
+      results = rules.map { |rule| Evaluators::ContextProperty.evaluate_single(rule, entity) }
+      req = (definition.context_requirement_type || definition.requirement_type || "Any").to_s
+      req.casecmp?("All") ? results.all? : results.any?
+    end
+
+    def evaluate_filter_group(rules, requirement_type, context, feature_key, result)
+      req = (requirement_type || "Any").to_s
+      evaluations = rules.map do |rule|
+        rule_type = rule["type"] || rule[:type] || rule["name"] || rule[:name] || "always_on"
+        evaluator = @registry.get(rule_type)
+        next false unless evaluator
+
+        begin
+          value = evaluator.evaluate(rule, context, feature_key: feature_key)
+          value == true
+        rescue StandardError
+          false
+        end
+      end
+      passed = req.casecmp?("All") ? evaluations.all? : evaluations.any?
+      result&.reason = passed ? "rule_matched" : "no_match" if result
+      passed
+    end
+
+    def sequential_rules(rules, definition, context, result)
+      rules.each_with_index do |rule, index|
+        rule_type = rule["type"] || rule[:type] || rule["name"] || rule[:name] || "always_on"
         evaluator = @registry.get(rule_type)
 
         unless evaluator
@@ -81,7 +126,6 @@ module Toggly
         begin
           evaluation = evaluator.evaluate(rule, context, feature_key: definition.feature_key)
 
-          # nil means continue to next rule
           next if evaluation.nil?
 
           if result
@@ -97,7 +141,6 @@ module Toggly
         end
       end
 
-      # No rules matched, default to enabled (since the feature itself is enabled)
       result&.reason = "default_enabled"
       true
     end

data/lib/toggly/evaluators/context_property.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Toggly
+  module Evaluators
+    # Evaluator for ContextProperty entity filters. Fail closed.
+    class ContextProperty < Base
+      def self.type
+        "contextproperty"
+      end
+
+      def evaluate(rule, context, feature_key: nil)
+        entity = context&.entity
+        return false unless entity
+
+        self.class.evaluate_single(rule, entity)
+      end
+
+      def self.context_property?(rule)
+        type = rule["type"] || rule[:type] || rule["name"] || rule[:name]
+        type.to_s.downcase == "contextproperty"
+      end
+
+      def self.evaluate_single(rule, entity)
+        property = rule_lookup(rule, "Property")
+        operator = rule_lookup(rule, "Operator")
+        expected = rule_lookup(rule, "Value")
+        value_type = (rule_lookup(rule, "ValueType") || "string").to_s.downcase
+        return false if property.to_s.strip.empty? || operator.to_s.strip.empty? || expected.nil?
+
+        operator = operator.to_s.downcase
+        return false unless entity.attribute?(property)
+
+        actual = entity.attribute(property)
+        compare(actual, operator, expected.to_s, value_type)
+      end
+
+      def self.rule_lookup(rule, key)
+        params = rule["parameters"] || rule[:parameters] || rule
+        params[key] || params[key.to_s] || params[key.to_sym] ||
+          params.find { |k, _| k.to_s.casecmp?(key.to_s) }&.last
+      end
+
+      def self.compare(actual, operator, expected, value_type)
+        case operator
+        when "eq"
+          actual.to_s.casecmp?(expected)
+        when "neq"
+          !actual.to_s.casecmp?(expected)
+        when "gt", "gte", "lt", "lte"
+          compare_ordered(actual, expected, value_type, operator)
+        when "in"
+          expected.split(",").map(&:strip).reject(&:empty?).any? { |c| c.casecmp?(actual.to_s) }
+        when "contains"
+          if value_type == "string[]"
+            Array(actual).any? { |v| v.to_s.casecmp?(expected) }
+          else
+            actual.to_s.downcase.include?(expected.downcase)
+          end
+        else
+          false
+        end
+      end
+
+      def self.compare_ordered(actual, expected, value_type, operator)
+        if value_type == "datetime"
+          a = Time.parse(actual.to_s)
+          e = Time.parse(expected.to_s)
+          cmp = a <=> e
+        elsif value_type == "number"
+          a = parse_number(actual)
+          e = parse_number(expected)
+          return false if a.nil? || e.nil?
+
+          cmp = a <=> e
+        else
+          return false
+        end
+        case operator
+        when "gt" then cmp.positive?
+        when "gte" then cmp >= 0
+        when "lt" then cmp.negative?
+        when "lte" then cmp <= 0
+        else false
+        end
+      rescue ArgumentError, TypeError
+        false
+      end
+
+      # Strict numeric parse. Invalid strings must not coerce to 0.0.
+      def self.parse_number(value)
+        n = Float(value)
+        return nil unless n.finite?
+
+        n
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end

data/lib/toggly/feature_definition.rb

@@ -30,7 +30,7 @@ module Toggly
     attr_reader :created_at
 
     # @return [Time, nil] When the feature was last updated
-    attr_reader :updated_at
+    attr_reader :updated_at, :requirement_type, :context_kind, :context_requirement_type
 
     # @return [String, nil] Feature description
     attr_reader :description
@@ -38,6 +38,7 @@ module Toggly
     # Feature types
     TYPES = %w[Release Experiment Ops Permission].freeze
 
+    # rubocop:disable Metrics/ParameterLists
     def initialize(
       feature_key:,
       feature_type: "Release",
@@ -46,7 +47,10 @@ module Toggly
       metadata: {},
       description: nil,
       created_at: nil,
-      updated_at: nil
+      updated_at: nil,
+      requirement_type: "Any",
+      context_kind: nil,
+      context_requirement_type: nil
     )
       @feature_key = feature_key.to_s
       @feature_type = validate_type(feature_type)
@@ -56,7 +60,11 @@ module Toggly
       @description = description
       @created_at = parse_time(created_at)
       @updated_at = parse_time(updated_at)
+      @requirement_type = requirement_type || "Any"
+      @context_kind = context_kind
+      @context_requirement_type = context_requirement_type
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Create from a hash (e.g., from JSON)
     #
@@ -84,7 +92,10 @@ module Toggly
         metadata: hash[:metadata] || {},
         description: hash[:description],
         created_at: hash[:createdAt] || hash[:created_at],
-        updated_at: hash[:updatedAt] || hash[:updated_at]
+        updated_at: hash[:updatedAt] || hash[:updated_at],
+        requirement_type: hash[:requirementType] || hash[:requirement_type] || "Any",
+        context_kind: hash[:contextKind] || hash[:context_kind],
+        context_requirement_type: hash[:contextRequirementType] || hash[:context_requirement_type]
       )
     end
 

data/lib/toggly/registry.rb

@@ -81,6 +81,7 @@ module Toggly
       register(Evaluators::Targeting.new)
       register(Evaluators::TimeWindow.new)
       register(Evaluators::ContextualTargeting.new)
+      register(Evaluators::ContextProperty.new)
     end
   end
 end

data/lib/toggly/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Toggly
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/toggly.rb

@@ -12,6 +12,8 @@ require_relative "toggly/evaluators/percentage"
 require_relative "toggly/evaluators/targeting"
 require_relative "toggly/evaluators/time_window"
 require_relative "toggly/evaluators/contextual_targeting"
+require_relative "toggly/evaluators/context_property"
+require_relative "toggly/entity_context"
 require_relative "toggly/registry"
 require_relative "toggly/evaluation_engine"
 require_relative "toggly/snapshot_providers/base"
@@ -89,6 +91,7 @@ module Toggly
     def reset!
       @client&.close
       @client = nil
+      clear_entity_context_registrations if respond_to?(:clear_entity_context_registrations)
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: toggly
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Ops.ai
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-03 00:00:00.000000000 Z
+date: 2026-08-24 00:00:00.000000000 Z
 dependencies: []
 description: High-performance Ruby SDK for Toggly feature flag management. Works with
   or without Toggly.io.
@@ -26,11 +26,13 @@ files:
 - lib/toggly/config.rb
 - lib/toggly/context.rb
 - lib/toggly/definitions_provider.rb
+- lib/toggly/entity_context.rb
 - lib/toggly/errors.rb
 - lib/toggly/evaluation_engine.rb
 - lib/toggly/evaluators/always_off.rb
 - lib/toggly/evaluators/always_on.rb
 - lib/toggly/evaluators/base.rb
+- lib/toggly/evaluators/context_property.rb
 - lib/toggly/evaluators/contextual_targeting.rb
 - lib/toggly/evaluators/percentage.rb
 - lib/toggly/evaluators/targeting.rb