star_gates 0.0.0 → 0.2.0

data/lib/star_gates/telemetry/prometheus_adapter.rb

@@ -0,0 +1,183 @@
+# frozen_string_literal: true
+
+require_relative 'telemetry_adapter'
+
+module StarGates
+  module Telemetry
+    class PrometheusAdapter < TelemetryAdapter
+      def initialize(config = {})
+        super
+        @prometheus = config[:prometheus] || default_prometheus
+        @metric_prefix = config[:metric_prefix] || 'star_gates'
+        @registry = {}
+        setup_default_metrics
+      end
+
+      protected
+
+      def send_metric(name, value, tags, _timestamp)
+        metric_name = "#{@metric_prefix}_#{name}".gsub('.', '_')
+
+        case name
+        when /\.gauge$/
+          get_or_create_gauge(metric_name, tags).set(value)
+        when /\.histogram$/, /\.timing$/
+          get_or_create_histogram(metric_name, tags).observe(value)
+        else
+          # Default to counter
+          get_or_create_counter(metric_name, tags).increment(by: value)
+        end
+      end
+
+      def healthy?
+        super && @prometheus.respond_to?(:registry)
+      end
+
+      private
+
+      def default_prometheus
+        unless defined?(Prometheus)
+          raise ArgumentError, "Prometheus gem not available. Install with: gem 'prometheus-client'"
+        end
+
+        Prometheus
+      end
+
+      def setup_default_metrics
+        # Pre-register common metrics for better performance
+        @registry[:feature_evaluations] = @prometheus.counter(
+          :"#{@metric_prefix}_feature_evaluations_total",
+          docstring: 'Total number of feature flag evaluations',
+          labels: %i[feature_id eligible]
+        )
+
+        @registry[:feature_executions] = @prometheus.counter(
+          :"#{@metric_prefix}_feature_executions_total",
+          docstring: 'Total number of feature flag executions',
+          labels: %i[feature_id state success]
+        )
+
+        @registry[:state_transitions] = @prometheus.counter(
+          :"#{@metric_prefix}_state_transitions_total",
+          docstring: 'Total number of feature flag state transitions',
+          labels: %i[feature_id from_state to_state event]
+        )
+
+        @registry[:execution_duration] = @prometheus.histogram(
+          :"#{@metric_prefix}_execution_duration_milliseconds",
+          docstring: 'Feature execution duration in milliseconds',
+          labels: %i[feature_id state],
+          buckets: [0.1, 0.5, 1, 2.5, 5, 10, 25, 50, 100, 250, 500, 1000]
+        )
+
+        @registry[:evaluation_duration] = @prometheus.histogram(
+          :"#{@metric_prefix}_evaluation_duration_milliseconds",
+          docstring: 'Feature evaluation duration in milliseconds',
+          labels: %i[feature_id eligible],
+          buckets: [0.01, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10]
+        )
+
+        @registry[:system_health] = @prometheus.gauge(
+          :"#{@metric_prefix}_system_health",
+          docstring: 'System health status (1 = healthy, 0 = unhealthy)',
+          labels: [:component]
+        )
+      end
+
+      def get_or_create_counter(name, tags)
+        key = "#{name}_counter"
+        @registry[key] ||= @prometheus.counter(
+          name.to_sym,
+          docstring: "Counter metric for #{name}",
+          labels: tags.keys
+        )
+        @registry[key].with(tags)
+      end
+
+      def get_or_create_gauge(name, tags)
+        key = "#{name}_gauge"
+        @registry[key] ||= @prometheus.gauge(
+          name.to_sym,
+          docstring: "Gauge metric for #{name}",
+          labels: tags.keys
+        )
+        @registry[key].with(tags)
+      end
+
+      def get_or_create_histogram(name, tags)
+        key = "#{name}_histogram"
+        @registry[key] ||= @prometheus.histogram(
+          name.to_sym,
+          docstring: "Histogram metric for #{name}",
+          labels: tags.keys,
+          buckets: default_timing_buckets
+        )
+        @registry[key].with(tags)
+      end
+
+      def default_timing_buckets
+        [0.1, 0.5, 1, 2.5, 5, 10, 25, 50, 100, 250, 500, 1000]
+      end
+
+      # Use pre-registered metrics for better performance
+      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
+        }
+
+        @registry[:feature_evaluations].increment(labels: tags)
+
+        return unless execution_time_ms
+
+        @registry[:evaluation_duration].observe(execution_time_ms, labels: {
+                                                  feature_id: feature_id.to_s,
+                                                  eligible: eligible.to_s
+                                                })
+      end
+
+      def record_feature_execution(feature_id, state, success, execution_time_ms, _context = {})
+        return unless enabled?
+
+        execution_tags = {
+          feature_id: feature_id.to_s,
+          state: state.to_s,
+          success: success.to_s
+        }
+
+        duration_tags = {
+          feature_id: feature_id.to_s,
+          state: state.to_s
+        }
+
+        @registry[:feature_executions].increment(labels: execution_tags)
+        @registry[:execution_duration].observe(execution_time_ms, labels: duration_tags)
+      end
+
+      def record_state_transition(feature_id, from_state, to_state, event_name)
+        return unless enabled?
+
+        tags = {
+          feature_id: feature_id.to_s,
+          from_state: from_state.to_s,
+          to_state: to_state.to_s,
+          event: event_name.to_s
+        }
+
+        @registry[:state_transitions].increment(labels: tags)
+      end
+
+      def record_system_health(healthy, component_healths = {})
+        return unless enabled?
+
+        @registry[:system_health].set(healthy ? 1 : 0, labels: { component: 'overall' })
+
+        component_healths.each do |component, health|
+          @registry[:system_health].set(health ? 1 : 0, labels: { component: component.to_s })
+        end
+      end
+    end
+  end
+end

data/lib/star_gates/telemetry/telemetry_adapter.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module StarGates
+  module Telemetry
+    class TelemetryAdapter
+      def initialize(config = {})
+        @config = config
+        @enabled = config.fetch(:enabled, true)
+      end
+
+      # Core telemetry methods
+      def record_metric(name, value, tags: {}, timestamp: Time.now)
+        return unless enabled?
+
+        send_metric(name, value, tags, timestamp)
+      end
+
+      def record_counter(name, value = 1, tags: {})
+        return unless enabled?
+
+        record_metric("#{name}.count", value, tags: tags)
+      end
+
+      def record_gauge(name, value, tags: {})
+        return unless enabled?
+
+        record_metric("#{name}.gauge", value, tags: tags)
+      end
+
+      def record_histogram(name, value, tags: {})
+        return unless enabled?
+
+        record_metric("#{name}.histogram", value, tags: tags)
+      end
+
+      def record_timing(name, duration_ms, tags: {})
+        return unless enabled?
+
+        record_metric("#{name}.timing", duration_ms, tags: tags)
+      end
+
+      # Feature flag specific metrics
+      def record_feature_evaluation(feature_id, eligible, _context, execution_time_ms = nil)
+        return unless enabled?
+
+        tags = {
+          feature_id: feature_id,
+          eligible: eligible
+        }
+
+        record_counter('star_gates.feature.evaluation', 1, tags: tags)
+
+        return unless execution_time_ms
+
+        record_timing('star_gates.feature.evaluation.duration', execution_time_ms, tags: tags)
+      end
+
+      def record_feature_execution(feature_id, state, success, execution_time_ms, _context = {})
+        return unless enabled?
+
+        tags = {
+          feature_id: feature_id,
+          state: state,
+          success: success
+        }
+
+        record_counter('star_gates.feature.execution', 1, tags: tags)
+        record_timing('star_gates.feature.execution.duration', execution_time_ms, tags: tags)
+      end
+
+      def record_state_transition(feature_id, from_state, to_state, event_name)
+        return unless enabled?
+
+        tags = {
+          feature_id: feature_id,
+          from_state: from_state,
+          to_state: to_state,
+          event: event_name
+        }
+
+        record_counter('star_gates.feature.transition', 1, tags: tags)
+      end
+
+      def record_circuit_breaker_event(feature_id, event_type, state)
+        return unless enabled?
+
+        tags = {
+          feature_id: feature_id,
+          event_type: event_type,
+          circuit_state: state
+        }
+
+        record_counter('star_gates.circuit_breaker.event', 1, tags: tags)
+      end
+
+      # System metrics
+      def record_system_health(healthy, component_healths = {})
+        return unless enabled?
+
+        record_gauge('star_gates.system.healthy', healthy ? 1 : 0)
+
+        component_healths.each do |component, health|
+          record_gauge('star_gates.system.component.healthy', health ? 1 : 0,
+                       tags: { component: component })
+        end
+      end
+
+      def record_event_store_metrics(event_count, aggregate_count, projection_lag_ms = nil)
+        return unless enabled?
+
+        record_gauge('star_gates.event_store.events', event_count)
+        record_gauge('star_gates.event_store.aggregates', aggregate_count)
+
+        return unless projection_lag_ms
+
+        record_timing('star_gates.event_store.projection_lag', projection_lag_ms)
+      end
+
+      # Time a block and record the duration
+      def time(metric_name, tags: {}, &block)
+        return block.call unless enabled?
+
+        start_time = Time.now
+        result = block.call
+        duration_ms = ((Time.now - start_time) * 1000).round(2)
+
+        record_timing(metric_name, duration_ms, tags: tags)
+        result
+      end
+
+      # Health check
+      def healthy?
+        enabled?
+      end
+
+      def enabled?
+        @enabled
+      end
+
+      def disable!
+        @enabled = false
+      end
+
+      def enable!
+        @enabled = true
+      end
+
+      protected
+
+      # Subclasses must implement this
+      def send_metric(name, value, tags, timestamp)
+        raise NotImplementedError, 'Subclasses must implement #send_metric'
+      end
+
+      private
+
+      attr_reader :config
+    end
+  end
+end

data/lib/star_gates/version.rb

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

data/lib/star_gates.rb

@@ -1,17 +1,317 @@
 # frozen_string_literal: true
 
-require "zeitwerk"
-require "breaker_machines"
+require 'zeitwerk'
+require 'active_support'
+require 'active_support/core_ext/numeric/time'
+require 'breaker_machines'
+require_relative 'star_gates/errors'
+require_relative 'star_gates/dsl'
+
+# Load all foundation modules manually first
+require_relative 'star_gates/events/base_event'
+require_relative 'star_gates/events/feature_events'
+require_relative 'star_gates/event_store/memory_adapter'
+require_relative 'star_gates/event_store/event_store'
+require_relative 'star_gates/adapters/base_adapter'
+require_relative 'star_gates/adapters/memory_adapter'
+require_relative 'star_gates/hexagonal/feature_aggregate'
+require_relative 'star_gates/hexagonal/feature_repository'
+require_relative 'star_gates/projections/feature_projection'
+require_relative 'star_gates/hexagonal/feature_service'
+require_relative 'star_gates/telemetry/telemetry_adapter'
 
 loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/star_gates/errors.rb")
+loader.ignore("#{__dir__}/star_gates/dsl.rb")
+loader.ignore("#{__dir__}/star_gates/events")
+loader.ignore("#{__dir__}/star_gates/event_store")
+loader.ignore("#{__dir__}/star_gates/adapters")
+loader.ignore("#{__dir__}/star_gates/hexagonal")
+loader.ignore("#{__dir__}/star_gates/projections")
+loader.ignore("#{__dir__}/star_gates/telemetry")
 loader.setup
 
 module StarGates
-  class Error < StandardError; end
-  
-  # DSL entry point for defining star gates
-  def self.define(&block)
-    # Implementation will be added later
-    raise NotImplementedError, "StarGates.define is not yet implemented"
+  @registry = Registry.new
+  @test_mode = false
+  @feature_service = nil
+
+  class << self
+    attr_reader :registry
+
+    def flags
+      @flags ||= Flags.new
+    end
+
+    def define(&)
+      context = DSL::DefineContext.new(registry)
+      context.instance_eval(&) if block_given?
+    end
+
+    def [](name)
+      gate = registry[name]
+      raise GateNotFoundError, "Gate #{name} not found" unless gate
+
+      gate
+    end
+
+    def activate(name, context = {})
+      self[name].call(context)
+    end
+
+    def status(name)
+      self[name].status
+    end
+
+    def gates
+      registry.keys
+    end
+
+    def test_mode!
+      @test_mode = true
+    end
+
+    def test_mode?
+      @test_mode
+    end
+
+    def production_mode!
+      @test_mode = false
+    end
+
+    def reset!
+      registry.clear
+    end
+
+    # Instrumentation for feature flag events
+    def instrument(event, payload = {})
+      return unless defined?(ActiveSupport::Notifications)
+
+      ActiveSupport::Notifications.instrument("star_gates.#{event}", payload)
+    end
+
+    # ============================================================================
+    # SYSTEM-LEVEL INTROSPECTION METHODS
+    # ============================================================================
+
+    # Overview of all features and their states
+    def feature_overview
+      gates = registry.to_h
+      overview = {
+        total_gates: gates.size,
+        gates: {},
+        summary: {
+          by_status: {},
+          total_features: 0,
+          features_with_circuits: 0
+        }
+      }
+
+      gates.each do |name, gate|
+        feature = gate.feature
+        circuit = gate.circuit
+
+        gate_info = {
+          name: name,
+          feature: feature&.to_h,
+          circuit: circuit ? circuit_info(circuit) : nil,
+          status: gate.status
+        }
+
+        overview[:gates][name] = gate_info
+
+        # Update summary statistics
+        if feature
+          overview[:summary][:total_features] += 1
+          status = feature.status
+          overview[:summary][:by_status][status] = (overview[:summary][:by_status][status] || 0) + 1
+        end
+
+        overview[:summary][:features_with_circuits] += 1 if circuit
+      end
+
+      overview
+    end
+
+    # System-wide rollout statistics
+    def rollout_statistics
+      gates = registry.to_h
+      stats = {
+        total_gates: gates.size,
+        features_by_status: Hash.new(0),
+        average_rollout: 0,
+        rollout_distribution: {},
+        generated_at: Time.now
+      }
+
+      rollout_percentages = []
+
+      gates.each_value do |gate|
+        feature = gate.feature
+        next unless feature
+
+        status = feature.status
+        stats[:features_by_status][status] += 1
+
+        next unless feature.status == 'canary'
+
+        rollout_percentages << feature.rollout_percentage
+
+        range = case feature.rollout_percentage
+                when 0...10 then '0-9%'
+                when 10...25 then '10-24%'
+                when 25...50 then '25-49%'
+                when 50...75 then '50-74%'
+                when 75...100 then '75-99%'
+                else '100%'
+                end
+
+        stats[:rollout_distribution][range] = (stats[:rollout_distribution][range] || 0) + 1
+      end
+
+      stats[:average_rollout] =
+        rollout_percentages.any? ? (rollout_percentages.sum / rollout_percentages.size).round(2) : 0
+
+      stats
+    end
+
+    # Distribution of features across states
+    def state_distribution
+      gates = registry.to_h
+      distribution = Hash.new(0)
+
+      gates.each_value do |gate|
+        feature = gate.feature
+        next unless feature
+
+        distribution[feature.status] += 1
+      end
+
+      {
+        distribution: distribution,
+        total: distribution.values.sum,
+        percentages: distribution.transform_values do |count|
+          total = distribution.values.sum
+          total.positive? ? (count.to_f / total * 100).round(2) : 0
+        end
+      }
+    end
+
+    # Recent state transitions across all features
+    def recent_transitions(limit: 10)
+      if feature_service_enabled?
+        feature_service.recent_transitions(limit: limit)
+      else
+        # Fallback to legacy implementation
+        gates = registry.to_h
+        all_transitions = []
+
+        gates.each_value do |gate|
+          feature = gate.feature
+          next unless feature
+
+          feature_transitions = feature.instance_variable_get(:@transition_history)
+          next unless feature_transitions
+
+          all_transitions.concat(feature_transitions.to_a)
+        end
+
+        # Sort by timestamp descending and take the most recent
+        recent = all_transitions.sort_by { |t| -t[:timestamp].to_f }.first(limit)
+
+        {
+          transitions: recent.map do |transition|
+            {
+              timestamp: transition[:timestamp],
+              feature_name: transition[:feature_name],
+              feature_class: transition[:feature_class],
+              from_state: transition[:from_state],
+              to_state: transition[:to_state],
+              event: transition[:event],
+              duration_since: Time.now - transition[:timestamp]
+            }
+          end,
+          total_found: all_transitions.size,
+          limit: limit,
+          generated_at: Time.now
+        }
+      end
+    end
+
+    # Configure the foundational architecture
+    def configure_foundation(event_store: nil, adapter: nil, telemetry: nil)
+      event_store ||= EventStore::EventStore.new
+      adapter ||= Adapters::MemoryAdapter.new
+
+      repository = Hexagonal::FeatureRepository.new(event_store)
+      projection = Projections::FeatureProjection.new(adapter)
+
+      @feature_service = Hexagonal::FeatureService.new(
+        repository: repository,
+        projection: projection,
+        event_store: event_store
+      )
+
+      @telemetry_adapter = telemetry if telemetry
+
+      @feature_service
+    end
+
+    # Access to the feature service (lazy initialization)
+    def feature_service
+      @feature_service ||= configure_foundation
+    end
+
+    # Check if feature service is enabled
+    def feature_service_enabled?
+      !@feature_service.nil?
+    end
+
+    # Enable event sourcing mode
+    def enable_event_sourcing!
+      configure_foundation unless feature_service_enabled?
+    end
+
+    # Telemetry integration
+    def telemetry
+      @telemetry_adapter
+    end
+
+    def configure_telemetry(adapter)
+      @telemetry_adapter = adapter
+    end
+
+    # Check if jsonrpc-rails is available
+    def jsonrpc_rails_available?
+      defined?(JSON_RPC) && defined?(ActionController::Base)
+    end
+
+    private
+
+    def circuit_info(circuit)
+      if circuit.respond_to?(:to_h)
+        circuit.to_h
+      elsif circuit.respond_to?(:stats)
+        circuit.stats
+      else
+        { status: circuit.respond_to?(:status) ? circuit.status : 'unknown' }
+      end
+    end
   end
 end
+
+# Percentage shorthand for the feature DSL.
+class Numeric
+  def percent
+    self
+  end
+end
+
+# Optional jsonrpc-rails integration
+begin
+  require 'rails'
+  require 'jsonrpc-rails'
+  require_relative 'star_gates/jsonrpc_rails_adapter'
+rescue LoadError
+  # jsonrpc-rails or Rails not available, skip integration
+end