star_gates 0.0.0 → 0.2.0

data/lib/star_gates/hexagonal/feature_aggregate.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require_relative '../events/feature_events'
+
+module StarGates
+  module Hexagonal
+    class FeatureAggregate
+      attr_reader :id, :version, :uncommitted_events
+
+      def initialize(id, events = [])
+        @id = id
+        @version = 0
+        @uncommitted_events = []
+        @state = {}
+
+        # Replay events to rebuild state
+        events.each { |event| apply_event(event, from_history: true) }
+      end
+
+      # Command: Create feature
+      def create(rollout: 0, group: nil, metadata: {})
+        raise ArgumentError, 'Feature already exists' if created?
+
+        event = Events::FeatureCreated.new(
+          aggregate_id: @id,
+          data: {
+            rollout_percentage: parse_rollout(rollout),
+            group_matcher: group,
+            metadata: metadata
+          }
+        )
+
+        apply_event(event)
+      end
+
+      # Command: Change state
+      def change_state(from_state, to_state, event_name, context = {})
+        unless can_transition?(from_state, to_state, event_name)
+          raise InvalidTransitionError, "Cannot transition from #{from_state} to #{to_state} via #{event_name}"
+        end
+
+        event = Events::FeatureStateChanged.new(
+          aggregate_id: @id,
+          from_state: from_state,
+          to_state: to_state,
+          event_name: event_name,
+          context: context
+        )
+
+        apply_event(event)
+      end
+
+      # Command: Update configuration
+      def update_configuration(changes)
+        event = Events::FeatureConfigurationChanged.new(
+          aggregate_id: @id,
+          configuration_changes: changes
+        )
+
+        apply_event(event)
+      end
+
+      # Command: Record execution
+      def record_execution(context, result, execution_time)
+        event = Events::FeatureExecuted.new(
+          aggregate_id: @id,
+          context: context,
+          result: result,
+          execution_time: execution_time
+        )
+
+        apply_event(event)
+      end
+
+      # Command: Record evaluation
+      def record_evaluation(context, eligible, reason)
+        event = Events::FeatureEvaluated.new(
+          aggregate_id: @id,
+          context: context,
+          eligible: eligible,
+          reason: reason
+        )
+
+        apply_event(event)
+      end
+
+      # Queries
+      def created?
+        @state[:created] || false
+      end
+
+      def current_state
+        @state[:current_state] || :disabled
+      end
+
+      def rollout_percentage
+        @state[:rollout_percentage] || 0
+      end
+
+      def group_matcher
+        @state[:group_matcher]
+      end
+
+      def configuration
+        @state[:configuration] || {}
+      end
+
+      def transition_history
+        @state[:transitions] || []
+      end
+
+      def execution_history
+        @state[:executions] || []
+      end
+
+      def evaluation_history
+        @state[:evaluations] || []
+      end
+
+      # Mark events as committed
+      def mark_events_as_committed
+        @uncommitted_events.clear
+      end
+
+      # Get snapshot for rebuilding
+      def to_snapshot
+        {
+          id: @id,
+          version: @version,
+          state: @state.dup
+        }
+      end
+
+      # Load from snapshot
+      def self.from_snapshot(snapshot, events_since_snapshot = [])
+        aggregate = allocate
+        aggregate.instance_variable_set(:@id, snapshot[:id])
+        aggregate.instance_variable_set(:@version, snapshot[:version])
+        aggregate.instance_variable_set(:@state, snapshot[:state].dup)
+        aggregate.instance_variable_set(:@uncommitted_events, [])
+
+        # Apply events since snapshot
+        events_since_snapshot.each { |event| aggregate.apply_event(event, from_history: true) }
+
+        aggregate
+      end
+
+      private
+
+      def apply_event(event, from_history: false)
+        case event
+        when Events::FeatureCreated
+          apply_feature_created(event)
+        when Events::FeatureStateChanged
+          apply_state_changed(event)
+        when Events::FeatureConfigurationChanged
+          apply_configuration_changed(event)
+        when Events::FeatureExecuted
+          apply_execution_recorded(event)
+        when Events::FeatureEvaluated
+          apply_evaluation_recorded(event)
+        end
+
+        @version += 1 if from_history
+        @uncommitted_events << event unless from_history
+      end
+
+      def apply_feature_created(event)
+        @state[:created] = true
+        @state[:current_state] = :disabled
+        @state[:rollout_percentage] = event.data[:rollout_percentage]
+        @state[:group_matcher] = event.data[:group_matcher]
+        @state[:metadata] = event.data[:metadata]
+        @state[:transitions] = []
+        @state[:executions] = []
+        @state[:evaluations] = []
+        @state[:configuration] = {}
+      end
+
+      def apply_state_changed(event)
+        @state[:current_state] = event.to_state
+        @state[:transitions] ||= []
+        @state[:transitions] << {
+          from_state: event.from_state,
+          to_state: event.to_state,
+          event_name: event.event_name,
+          context: event.context,
+          occurred_at: event.occurred_at
+        }
+
+        # Keep only last 50 transitions for memory efficiency
+        @state[:transitions] = @state[:transitions].last(50) if @state[:transitions].size > 50
+      end
+
+      def apply_configuration_changed(event)
+        @state[:configuration] ||= {}
+        @state[:configuration].merge!(event.configuration_changes)
+      end
+
+      def apply_execution_recorded(event)
+        @state[:executions] ||= []
+        @state[:executions] << {
+          context: event.context,
+          result: event.result,
+          execution_time: event.execution_time,
+          occurred_at: event.occurred_at
+        }
+
+        # Keep only last 100 executions
+        @state[:executions] = @state[:executions].last(100) if @state[:executions].size > 100
+      end
+
+      def apply_evaluation_recorded(event)
+        @state[:evaluations] ||= []
+        @state[:evaluations] << {
+          context: event.context,
+          eligible: event.eligible,
+          reason: event.reason,
+          occurred_at: event.occurred_at
+        }
+
+        # Keep only last 100 evaluations
+        @state[:evaluations] = @state[:evaluations].last(100) if @state[:evaluations].size > 100
+      end
+
+      def can_transition?(from_state, to_state, event_name)
+        # Define valid transitions
+        valid_transitions = {
+          disabled: { rollout_canary: :canary, enable: :enabled },
+          canary: { enable: :enabled, disable: :disabled },
+          enabled: { disable: :disabled, rollout_canary: :canary }
+        }
+
+        allowed_transitions = valid_transitions[from_state.to_sym] || {}
+        allowed_transitions[event_name.to_sym] == to_state.to_sym
+      end
+
+      def parse_rollout(rollout)
+        case rollout
+        when Numeric, String
+          rollout.to_i
+        else
+          0
+        end
+      end
+
+      class InvalidTransitionError < StandardError; end
+    end
+  end
+end

data/lib/star_gates/hexagonal/feature_repository.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative 'feature_aggregate'
+
+module StarGates
+  module Hexagonal
+    class FeatureRepository
+      def initialize(event_store)
+        @event_store = event_store
+      end
+
+      # Load feature aggregate from event store
+      def find(feature_id)
+        events = @event_store.get_events(feature_id)
+        return nil if events.empty?
+
+        FeatureAggregate.new(feature_id, events)
+      end
+
+      # Save feature aggregate to event store
+      def save(aggregate, expected_version: nil)
+        return if aggregate.uncommitted_events.empty?
+
+        @event_store.append(
+          aggregate.id,
+          aggregate.uncommitted_events,
+          expected_version: expected_version
+        )
+
+        aggregate.mark_events_as_committed
+      end
+
+      # Find or create feature aggregate
+      def find_or_create(feature_id)
+        find(feature_id) || FeatureAggregate.new(feature_id)
+      end
+
+      # Check if feature exists
+      def exists?(feature_id)
+        @event_store.get_version(feature_id).positive?
+      end
+
+      # Get all feature IDs that have events
+      def all_feature_ids
+        # This would need to be implemented by the event store adapter
+        # For now, we'll return an empty array as this requires scanning
+        []
+      end
+
+      # Get features by state (requires read model/projection)
+      def find_by_state(state)
+        # This would typically be implemented using a read model/projection
+        # For now, we'll raise an error to indicate this needs a projection
+        raise NotImplementedError, 'Use FeatureProjection to query by state'
+      end
+
+      # Health check
+      def healthy?
+        @event_store.respond_to?(:healthy?) ? @event_store.healthy? : true
+      end
+
+      private
+
+      attr_reader :event_store
+    end
+  end
+end

data/lib/star_gates/hexagonal/feature_service.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative 'feature_repository'
+require_relative '../projections/feature_projection'
+
+module StarGates
+  module Hexagonal
+    class FeatureService
+      def initialize(repository:, projection:, event_store:)
+        @repository = repository
+        @projection = projection
+        @event_store = event_store
+        setup_event_subscriptions
+      end
+
+      # Commands
+      def create_feature(feature_id, rollout: 0, group: nil, metadata: {})
+        aggregate = @repository.find_or_create(feature_id)
+
+        unless aggregate.created?
+          aggregate.create(rollout: rollout, group: group, metadata: metadata)
+          @repository.save(aggregate)
+        end
+
+        aggregate
+      end
+
+      def change_feature_state(feature_id, from_state, to_state, event_name, context = {})
+        aggregate = @repository.find(feature_id)
+        raise FeatureNotFoundError, "Feature #{feature_id} not found" unless aggregate
+
+        aggregate.change_state(from_state, to_state, event_name, context)
+        @repository.save(aggregate)
+
+        aggregate
+      end
+
+      def update_feature_configuration(feature_id, changes)
+        aggregate = @repository.find(feature_id)
+        raise FeatureNotFoundError, "Feature #{feature_id} not found" unless aggregate
+
+        aggregate.update_configuration(changes)
+        @repository.save(aggregate)
+
+        aggregate
+      end
+
+      def record_feature_execution(feature_id, context, result, execution_time)
+        aggregate = @repository.find(feature_id)
+        return unless aggregate # Silently skip if feature doesn't exist
+
+        aggregate.record_execution(context, result, execution_time)
+        @repository.save(aggregate)
+      end
+
+      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(context, eligible, reason)
+        @repository.save(aggregate)
+      end
+
+      # Queries (delegated to projection)
+      def find_feature(feature_id)
+        @projection.find_feature(feature_id)
+      end
+
+      def find_features_by_state(state)
+        @projection.find_features_by_state(state)
+      end
+
+      def all_features
+        @projection.all_features
+      end
+
+      def feature_stats
+        @projection.feature_stats
+      end
+
+      def recent_transitions(limit: 10)
+        @projection.recent_transitions(limit: limit)
+      end
+
+      def feature_exists?(feature_id)
+        @projection.feature_exists?(feature_id)
+      end
+
+      # Get feature aggregate for complex operations
+      def get_feature_aggregate(feature_id)
+        @repository.find(feature_id)
+      end
+
+      # Replay events to rebuild projections
+      def rebuild_projections!
+        @projection.clear! if @projection.respond_to?(:clear!)
+
+        @event_store.replay_all do |event|
+          @projection.handle_event(event)
+        end
+      end
+
+      # Health check
+      def healthy?
+        @repository.healthy? &&
+          (@event_store.respond_to?(:healthy?) ? @event_store.healthy? : true)
+      end
+
+      private
+
+      def setup_event_subscriptions
+        # Subscribe to all events to update projections
+        @event_store.subscribe do |event|
+          @projection.handle_event(event)
+        end
+      end
+
+      class FeatureNotFoundError < StandardError; end
+    end
+  end
+end

data/lib/star_gates/jsonrpc_rails_adapter.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module StarGates
+  # Optional JSON-RPC adapter using jsonrpc-rails gem
+  # Include this in your Rails controllers when jsonrpc-rails is available
+  module JsonrpcRailsAdapter
+    def self.available?
+      defined?(JSON_RPC) && defined?(ActionController::Base)
+    end
+
+    def self.included(_base)
+      return if available?
+
+      raise LoadError, "jsonrpc-rails gem is required. Add 'gem \"jsonrpc-rails\"' to your Gemfile"
+    end
+
+    # Main JSON-RPC request handler
+    def process
+      if jsonrpc_params_batch?
+        # Handle batch requests
+        responses = jsonrpc_params.filter_map { |req| handle_single_request(req) }
+
+        if responses.empty?
+          head :no_content
+        else
+          render json: responses.map(&:to_h), status: :ok
+        end
+      else
+        # Handle single request
+        response = handle_single_request(jsonrpc_params)
+
+        if response # request (has id)
+          render jsonrpc: response.result,
+                 id: response.id,
+                 error: response.error
+        else # notification
+          head :no_content
+        end
+      end
+    end
+
+    private
+
+    # Map one JSON_RPC::Request|Notification → Response|nil
+    def handle_single_request(req)
+      # Notifications have id == nil. Return nil = no response.
+      return nil if req.id.nil?
+
+      result_or_error = dispatch_method(req.method, req.params || {})
+      build_response(req.id, result_or_error)
+    end
+
+    # Dispatch JSON-RPC method to appropriate handler
+    def dispatch_method(method, params)
+      case method
+      when 'feature.create'
+        create_feature(params)
+      when 'feature.get'
+        get_feature(params)
+      when 'feature.list'
+        list_features(params)
+      when 'feature.changeState'
+        change_state(params)
+      when 'feature.execute'
+        execute_feature(params)
+      when 'feature.evaluate'
+        evaluate_feature(params)
+      when 'feature.stats'
+        feature_stats(params)
+      when 'feature.recentTransitions'
+        recent_transitions(params)
+      when 'system.health'
+        system_health(params)
+      when 'system.rebuildProjections'
+        rebuild_projections(params)
+      else
+        JSON_RPC::JsonRpcError.build(:method_not_found)
+      end
+    end
+
+    # Feature management methods
+    def create_feature(params)
+      validate_required_params(params, ['featureId'])
+
+      feature_id = params['featureId']
+      rollout = params['rollout'] || 0
+      group = params['group']
+      metadata = params['metadata'] || {}
+
+      aggregate = feature_service.create_feature(feature_id, rollout: rollout, group: group, metadata: metadata)
+
+      {
+        featureId: aggregate.id,
+        created: aggregate.created?,
+        state: aggregate.current_state,
+        rolloutPercentage: aggregate.rollout_percentage,
+        groupMatcher: aggregate.group_matcher
+      }
+    rescue StandardError => e
+      JSON_RPC::JsonRpcError.build(:invalid_params, data: { error: e.message })
+    end
+
+    def get_feature(params)
+      validate_required_params(params, ['featureId'])
+
+      feature = feature_service.find_feature(params['featureId'])
+      return JSON_RPC::JsonRpcError.build(:invalid_params, data: { error: 'Feature not found' }) unless feature
+
+      feature
+    rescue StandardError => e
+      JSON_RPC::JsonRpcError.build(:internal_error, data: { error: e.message })
+    end
+
+    def list_features(params)
+      state = params['state']
+
+      features = if state
+                   feature_service.find_features_by_state(state.to_sym)
+                 else
+                   feature_service.all_features
+                 end
+
+      { features: features }
+    rescue StandardError => e
+      JSON_RPC::JsonRpcError.build(:internal_error, data: { error: e.message })
+    end
+
+    def change_state(params)
+      validate_required_params(params, %w[featureId fromState toState event])
+
+      feature_id = params['featureId']
+      from_state = params['fromState'].to_sym
+      to_state = params['toState'].to_sym
+      event_name = params['event'].to_sym
+      context = params['context'] || {}
+
+      aggregate = feature_service.change_feature_state(feature_id, from_state, to_state, event_name, context)
+
+      {
+        featureId: aggregate.id,
+        fromState: from_state,
+        toState: to_state,
+        event: event_name,
+        success: true
+      }
+    rescue StandardError => e
+      JSON_RPC::JsonRpcError.build(:invalid_params, data: { error: "State transition failed: #{e.message}" })
+    end
+
+    def execute_feature(params)
+      validate_required_params(params, ['featureId'])
+
+      feature_id = params['featureId']
+      context = params['context'] || {}
+
+      start_time = Time.now
+      result = yield if block_given? # Allow caller to provide execution block
+      execution_time = ((Time.now - start_time) * 1000).round(2) # ms
+
+      feature_service.record_feature_execution(feature_id, context, result, execution_time)
+
+      {
+        featureId: feature_id,
+        result: result,
+        executionTime: execution_time,
+        context: context
+      }
+    rescue StandardError => e
+      JSON_RPC::JsonRpcError.build(:internal_error, data: { error: e.message })
+    end
+
+    def evaluate_feature(params)
+      validate_required_params(params, %w[featureId context])
+
+      feature_id = params['featureId']
+      context = params['context']
+      eligible = params['eligible'] || false
+      reason = params['reason'] || 'No reason provided'
+
+      feature_service.record_feature_evaluation(feature_id, context, eligible, reason)
+
+      {
+        featureId: feature_id,
+        context: context,
+        eligible: eligible,
+        reason: reason,
+        recordedAt: Time.now.utc.iso8601
+      }
+    rescue StandardError => e
+      JSON_RPC::JsonRpcError.build(:internal_error, data: { error: e.message })
+    end
+
+    def feature_stats(_params)
+      feature_service.feature_stats
+    rescue StandardError => e
+      JSON_RPC::JsonRpcError.build(:internal_error, data: { error: e.message })
+    end
+
+    def recent_transitions(params)
+      limit = params['limit'] || 10
+
+      {
+        transitions: feature_service.recent_transitions(limit: limit),
+        limit: limit
+      }
+    rescue StandardError => e
+      JSON_RPC::JsonRpcError.build(:internal_error, data: { error: e.message })
+    end
+
+    def system_health(_params)
+      {
+        healthy: feature_service.healthy?,
+        timestamp: Time.now.utc.iso8601,
+        version: StarGates::VERSION
+      }
+    rescue StandardError => e
+      JSON_RPC::JsonRpcError.build(:internal_error, data: { error: e.message })
+    end
+
+    def rebuild_projections(_params)
+      feature_service.rebuild_projections!
+
+      {
+        success: true,
+        rebuiltAt: Time.now.utc.iso8601
+      }
+    rescue StandardError => e
+      JSON_RPC::JsonRpcError.build(:internal_error, data: { error: e.message })
+    end
+
+    # Helper methods
+    def validate_required_params(params, required_keys)
+      missing_keys = required_keys - params.keys
+      return if missing_keys.empty?
+
+      raise ArgumentError, "Missing required parameters: #{missing_keys.join(', ')}"
+    end
+
+    def build_response(id, outcome)
+      if outcome.is_a?(JSON_RPC::JsonRpcError)
+        JSON_RPC::Response.new(id: id, error: outcome)
+      else
+        JSON_RPC::Response.new(id: id, result: outcome)
+      end
+    end
+
+    def feature_service
+      @feature_service ||= StarGates.feature_service
+    end
+  end
+end