star_gates 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2747943c57b6c5a1d42a415ec8321bcab9420438f3425424432a35ada2571c97
-  data.tar.gz: 375a4a1f9f7d27ec78d35386bb973f37c5723a2ff7a37eb580d5cd9d80f9f686
+  metadata.gz: 9150966ca03ffe47ce938c669d38ab3291e25b6b7aaea9560e89099ec255a65d
+  data.tar.gz: 0454b43be544e3c50026811f5d44ec3a28903c4ff824fcf3b855aaf70a733aba
 SHA512:
-  metadata.gz: db442d9496bc8ecaaae6a329c0b2bae1ac6f99a8a4375b57ec3e950941e7257c4a45045d1eb66494c2e74fc3c3075429ddf193173446ae09189b11b4dbfe8d2a
-  data.tar.gz: 9954bf6fccad1f849cd5fb411c3b79f2516ea46dc7b99da86ee4a373d3b4eb06e68cc14ba07a43c8c960bc4a0e5cf69086b40c5807495b79f3d4d250ce6fd7d6
+  metadata.gz: 4d7802feb0b5ebc3aefcd585224cfd5dda9f95e9e8f23ee5653a087f5326d14764ce7e6a06d16ca01cafd60570325c910cb776464b2abce14b2ef05b0a202407
+  data.tar.gz: 3e57ca2506afe07616e9c884f1f74228c2f380601a0ca4779b311a422aa0c215d228835e9160b0689db744ec788252b752f5133703992063a06c6c7db87254d7

data/CHANGELOG.md

@@ -2,8 +2,13 @@
 
 ## Unreleased
 
+## 0.2.0 (2026-10-28)
+
 ### Changed
 
+- Use explicit rollout `key:` and `groups:` context. Group predicates receive the
+  full context; simulation, debugging, and scenario analysis use key-based inputs
+  and results. Remove user-specific helpers and telemetry labels.
 - Require Ruby 4.0 or newer.
 - Require StateMachines 0.202.0 or newer.
 - Change the license to BSD-3-Clause.
@@ -17,6 +22,9 @@
 
 ### Fixed
 
+- Keep percentage rollout cohorts stable across workers and restarts with CRC32
+  key buckets. Upgrading reassigns cohorts previously based on Ruby's
+  process-randomized string hashes.
 - Correct dummy-app feature routing, persistent feature transitions, and circuit statistics.
 - Make weather demo failures explicit instead of random.
 

data/README.md

@@ -65,12 +65,20 @@ end
 
 gate = StarGates[:payments]
 gate.feature.rollout_canary
-gate.call(user: current_user, amount: 100)
+gate.call(key: 'account:42', amount: 100)
 ```
 
 Features start disabled. Use `rollout_canary` for percentage/group targeting,
-`enable` for full rollout, and `disable` to turn a feature off. Provide a user with
-an `id` for consistent percentage targeting.
+`enable` for full rollout, and `disable` to turn a feature off. Pass a stable
+string or integer `key:` for percentage targeting, such as an account, resident,
+or device identifier.
+
+Percentage targeting stays consistent across workers and restarts. Increasing
+the rollout percentage retains keys already included.
+
+For group targeting, pass `groups: [:beta]` to match `feature group: :beta`.
+A predicate such as `feature group: ->(context) { context[:region] == 'eu' }`
+receives the full context passed to the gate.
 
 When a circuit opens, its feature rolls back from enabled to canary, or from canary
 to disabled. Gates use their fallback when the feature is unavailable or execution
@@ -101,7 +109,7 @@ Define gates in an initializer and call them from controllers or services:
 ```ruby
 class PaymentsController < ApplicationController
   def create
-    result = StarGates[:payments].call(user: current_user, amount: params[:amount])
+    result = StarGates[:payments].call(key: "account:#{current_account.id}", amount: params[:amount])
     render json: result
   end
 end
@@ -153,15 +161,14 @@ require_relative 'test/dummy/app/models/spaceship'
 ship = Spaceship.new('SG Atlas', 'SG-1')
 warp = ship.gate(:warp_drive) # A StarGates::Gate, with a feature and a circuit.
 warp.feature.rollout_canary
-pilot = StarGates::Feature::MockUser.new(id: 1, groups: [:pilots])
-ship.engage_warp('Alpha Centauri', pilot: pilot)
+ship.engage_warp('Alpha Centauri', key: 'crew:1', groups: [:pilots])
 ```
 
 ### Application examples
 
 - [Payment feature](test/dummy/demos/payment_feature.rb): state-specific feature behavior.
 - [Transition history](test/dummy/demos/transition_demo.rb): recorded feature transitions.
-- [Introspection](test/dummy/demos/introspection_demo.rb): status, analytics, and user simulation.
+- [Introspection](test/dummy/demos/introspection_demo.rb): status, analytics, and context simulation.
 - [Application payment feature](test/dummy/demos/application_payment_feature.rb): application-level features.
 - [JSON-RPC controller](test/dummy/demos/jsonrpc_rails_controller.rb): optional JSON-RPC integration.
 

data/lib/star_gates/events/base_event.rb

@@ -13,7 +13,6 @@ module StarGates
         @event_type = self.class.name.split('::').last
         @data = data.freeze
         @metadata = metadata.merge(
-          created_by: Thread.current[:current_user_id],
           source: 'star_gates',
           correlation_id: Thread.current[:correlation_id] || SecureRandom.uuid
         ).freeze

data/lib/star_gates/events/feature_events.rb

@@ -58,11 +58,11 @@ module StarGates
     end
 
     class FeatureEvaluated < BaseEvent
-      def initialize(aggregate_id:, user_context:, eligible:, reason:, **opts)
+      def initialize(aggregate_id:, context:, eligible:, reason:, **opts)
         super(
           aggregate_id: aggregate_id,
           data: {
-            user_context: user_context,
+            context: context,
             eligible: eligible,
             reason: reason
           },
@@ -70,7 +70,7 @@ module StarGates
         )
       end
 
-      def user_context = data[:user_context]
+      def context = data[:context]
       def eligible = data[:eligible]
       def reason = data[:reason]
     end

data/lib/star_gates/feature.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'zlib'
 require 'state_machines'
 require 'concurrent'
 
@@ -120,17 +121,15 @@ module StarGates
       !disabled?
     end
 
-    # Check if user is eligible for rollout based on percentage and group
     def eligible_for_rollout?(context = {})
       return group_matches?(context) if group_matcher
       return false if rollout_percentage.zero?
       return true if rollout_percentage == 100
 
-      user_id = extract_user_id(context)
-      return false unless user_id
+      key = rollout_key(context)
+      return false if key.nil?
 
-      user_hash = hash_user_id(user_id)
-      (user_hash % 100) < rollout_percentage
+      (hash_key(key) % 100) < rollout_percentage
     end
 
     # Configuration methods for state-specific behavior
@@ -175,9 +174,9 @@ module StarGates
     def summary
       case status
       when 'disabled'
-        "Feature '#{feature_name}' is DISABLED. No users have access."
+        "Feature '#{feature_name}' is DISABLED. No keys are eligible."
       when 'enabled'
-        "Feature '#{feature_name}' is ENABLED for all users (100% rollout)."
+        "Feature '#{feature_name}' is ENABLED for all keys (100% rollout)."
       when 'canary'
         if group_matcher
           "Feature '#{feature_name}' is in CANARY mode for group #{group_matcher} (#{rollout_percentage}% rollout)."
@@ -202,20 +201,15 @@ module StarGates
       }
     end
 
-    # Mock user struct for testing (Data.define is Ruby 3.2+)
-    MockUser = Data.define(:id, :groups) unless defined?(self::MockUser)
-
-    # Test what a specific user would experience
-    def simulate_for_user(user_id:, user_groups: [])
-      mock_user = MockUser.new(id: user_id, groups: user_groups)
-      context = { user: mock_user }
+    def simulate(key:, groups: [], **attributes)
+      context = attributes.merge(key: key, groups: groups)
 
       eligible = enabled_for?(context)
       ui_component_result = ui_component(context)
 
       {
-        user_id: user_id,
-        user_groups: user_groups,
+        key: key,
+        groups: groups,
         eligible: eligible,
         reason: eligibility_reason(context),
         ui_component: ui_component_result,
@@ -224,13 +218,11 @@ module StarGates
       }
     end
 
-    # Debug why a user is or isn't eligible
-    def eligibility_debug(user:)
-      context = { user: user }
-      user_id = extract_user_id(context)
+    def eligibility_debug(**context)
+      key = rollout_key(context)
 
       debug_info = {
-        user_id: user_id,
+        key: key,
         feature_status: status,
         rollout_percentage: rollout_percentage,
         group_matcher: group_matcher,
@@ -246,18 +238,18 @@ module StarGates
         if group_matcher
           group_match = group_matches?(context)
           debug_info[:group_match] = group_match
-          debug_info[:reason] = group_match ? 'User matches group criteria' : 'User does not match group criteria'
-        elsif user_id
-          user_hash = hash_user_id(user_id)
-          debug_info[:user_hash] = user_hash
-          debug_info[:hash_modulo] = user_hash % 100
-          debug_info[:reason] = if (user_hash % 100) < rollout_percentage
-                                  "User hash #{user_hash % 100} is within rollout #{rollout_percentage}%"
+          debug_info[:reason] = group_match ? 'Context matches group criteria' : 'Context does not match group criteria'
+        elsif !key.nil?
+          key_hash = hash_key(key)
+          debug_info[:key_hash] = key_hash
+          debug_info[:hash_modulo] = key_hash % 100
+          debug_info[:reason] = if (key_hash % 100) < rollout_percentage
+                                  "Key hash #{key_hash % 100} is within rollout #{rollout_percentage}%"
                                 else
-                                  "User hash #{user_hash % 100} is outside rollout #{rollout_percentage}%"
+                                  "Key hash #{key_hash % 100} is outside rollout #{rollout_percentage}%"
                                 end
         else
-          debug_info[:reason] = 'No user ID found in context'
+          debug_info[:reason] = 'No rollout key found in context'
         end
       end
 
@@ -265,21 +257,20 @@ module StarGates
     end
 
     # Test different rollout scenarios
-    def test_rollout_scenarios(percentages, sample_user_ids: (1..1000).to_a.sample(100))
+    def test_rollout_scenarios(percentages, sample_keys: (1..1000).to_a.sample(100))
       scenarios = {}
 
       percentages.each do |percentage|
         eligible_count = 0
-        sample_user_ids.each do |user_id|
-          user_hash = hash_user_id(user_id)
-          eligible_count += 1 if (user_hash % 100) < percentage
+        sample_keys.each do |key|
+          eligible_count += 1 if (hash_key(key) % 100) < percentage
         end
 
         scenarios[percentage] = {
           percentage: percentage,
-          sample_size: sample_user_ids.size,
-          eligible_users: eligible_count,
-          estimated_percentage: (eligible_count.to_f / sample_user_ids.size * 100).round(2)
+          sample_size: sample_keys.size,
+          eligible_keys: eligible_count,
+          estimated_percentage: (eligible_count.to_f / sample_keys.size * 100).round(2)
         }
       end
 
@@ -367,7 +358,7 @@ module StarGates
       when 'enabled'
         'Feature is fully enabled'
       when 'canary'
-        eligible_for_rollout?(context) ? 'User is eligible for rollout' : 'User is not eligible for rollout'
+        eligible_for_rollout?(context) ? 'Context is eligible for rollout' : 'Context is not eligible for rollout'
       else
         "Unknown status: #{status}"
       end
@@ -384,34 +375,23 @@ module StarGates
     def group_matches?(context)
       return false unless group_matcher
 
-      user = context[:user]
-      return false unless user
-
       case group_matcher
       when Symbol
-        user.respond_to?(:groups) && user.groups.include?(group_matcher)
+        Array(context[:groups]).include?(group_matcher)
       when Proc
-        group_matcher.call(user)
+        group_matcher.call(context)
       else
         false
       end
     end
 
-    def extract_user_id(context)
-      user = context[:user]
-      return nil unless user
-
-      if user.respond_to?(:id)
-        user.id
-      elsif user.respond_to?(:user_id)
-        user.user_id
-      elsif user.is_a?(String) || user.is_a?(Integer)
-        user
-      end
+    def rollout_key(context)
+      key = context[:key]
+      key if key.is_a?(String) || key.is_a?(Integer)
     end
 
-    def hash_user_id(user_id)
-      user_id.to_s.hash.abs
+    def hash_key(key)
+      Zlib.crc32(key.to_s)
     end
 
     # Record state transition with timestamp and metadata

data/lib/star_gates/hexagonal/feature_aggregate.rb

@@ -73,10 +73,10 @@ module StarGates
       end
 
       # Command: Record evaluation
-      def record_evaluation(user_context, eligible, reason)
+      def record_evaluation(context, eligible, reason)
         event = Events::FeatureEvaluated.new(
           aggregate_id: @id,
-          user_context: user_context,
+          context: context,
           eligible: eligible,
           reason: reason
         )
@@ -213,7 +213,7 @@ module StarGates
       def apply_evaluation_recorded(event)
         @state[:evaluations] ||= []
         @state[:evaluations] << {
-          user_context: event.user_context,
+          context: event.context,
           eligible: event.eligible,
           reason: event.reason,
           occurred_at: event.occurred_at

data/lib/star_gates/hexagonal/feature_service.rb

@@ -53,11 +53,11 @@ module StarGates
         @repository.save(aggregate)
       end
 
-      def record_feature_evaluation(feature_id, user_context, eligible, reason)
+      def record_feature_evaluation(feature_id, context, eligible, reason)
         aggregate = @repository.find(feature_id)
         return unless aggregate # Silently skip if feature doesn't exist
 
-        aggregate.record_evaluation(user_context, eligible, reason)
+        aggregate.record_evaluation(context, eligible, reason)
         @repository.save(aggregate)
       end
 

data/lib/star_gates/jsonrpc_rails_adapter.rb

@@ -170,18 +170,18 @@ module StarGates
     end
 
     def evaluate_feature(params)
-      validate_required_params(params, %w[featureId userContext])
+      validate_required_params(params, %w[featureId context])
 
       feature_id = params['featureId']
-      user_context = params['userContext']
+      context = params['context']
       eligible = params['eligible'] || false
       reason = params['reason'] || 'No reason provided'
 
-      feature_service.record_feature_evaluation(feature_id, user_context, eligible, reason)
+      feature_service.record_feature_evaluation(feature_id, context, eligible, reason)
 
       {
         featureId: feature_id,
-        userContext: user_context,
+        context: context,
         eligible: eligible,
         reason: reason,
         recordedAt: Time.now.utc.iso8601

data/lib/star_gates/telemetry/opentelemetry_adapter.rb

@@ -15,12 +15,11 @@ module StarGates
       end
 
       # OpenTelemetry-specific methods
-      def trace_feature_evaluation(feature_id, user_context, &block)
+      def trace_feature_evaluation(feature_id, _context, &block)
         return block.call unless enabled?
 
         @tracer.in_span('feature.evaluate', attributes: {
                           'feature.id' => feature_id,
-                          'feature.user_type' => extract_user_type(user_context),
                           'service.name' => @service_name,
                           'service.version' => @service_version
                         }) do |span|
@@ -192,13 +191,12 @@ module StarGates
       end
 
       # Override specific methods to use pre-created instruments
-      def record_feature_evaluation(feature_id, eligible, user_context, execution_time_ms = nil)
+      def record_feature_evaluation(feature_id, eligible, _context, execution_time_ms = nil)
         return unless enabled?
 
         attributes = {
           'feature.id' => feature_id.to_s,
           'feature.eligible' => eligible.to_s,
-          'feature.user_type' => extract_user_type(user_context),
           'service.name' => @service_name,
           'service.version' => @service_version
         }

data/lib/star_gates/telemetry/prometheus_adapter.rb

@@ -48,7 +48,7 @@ module StarGates
         @registry[:feature_evaluations] = @prometheus.counter(
           :"#{@metric_prefix}_feature_evaluations_total",
           docstring: 'Total number of feature flag evaluations',
-          labels: %i[feature_id eligible user_type]
+          labels: %i[feature_id eligible]
         )
 
         @registry[:feature_executions] = @prometheus.counter(
@@ -120,13 +120,12 @@ module StarGates
       end
 
       # Use pre-registered metrics for better performance
-      def record_feature_evaluation(feature_id, eligible, user_context, execution_time_ms = nil)
+      def record_feature_evaluation(feature_id, eligible, _context, execution_time_ms = nil)
         return unless enabled?
 
         tags = {
           feature_id: feature_id.to_s,
-          eligible: eligible.to_s,
-          user_type: extract_user_type(user_context)
+          eligible: eligible.to_s
         }
 
         @registry[:feature_evaluations].increment(labels: tags)

data/lib/star_gates/telemetry/telemetry_adapter.rb

@@ -40,13 +40,12 @@ module StarGates
       end
 
       # Feature flag specific metrics
-      def record_feature_evaluation(feature_id, eligible, user_context, execution_time_ms = nil)
+      def record_feature_evaluation(feature_id, eligible, _context, execution_time_ms = nil)
         return unless enabled?
 
         tags = {
           feature_id: feature_id,
-          eligible: eligible,
-          user_type: extract_user_type(user_context)
+          eligible: eligible
         }
 
         record_counter('star_gates.feature.evaluation', 1, tags: tags)
@@ -155,19 +154,6 @@ module StarGates
 
       private
 
-      def extract_user_type(user_context)
-        user = user_context[:user] if user_context.is_a?(Hash)
-        return 'unknown' unless user
-
-        if user.respond_to?(:groups) && user.groups.is_a?(Array)
-          return 'beta' if user.groups.include?(:beta_users)
-          return 'admin' if user.groups.include?(:admin)
-          return 'premium' if user.groups.include?(:premium)
-        end
-
-        'regular'
-      end
-
       attr_reader :config
     end
   end

data/lib/star_gates/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: star_gates
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Abdelkader Boudih
@@ -156,7 +156,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.20
 specification_version: 4
 summary: A Ruby gem for building DSL-based star gate configurations
 test_files: []