flow_chat 0.6.1 → 0.8.0

data/lib/flow_chat/config.rb

@@ -8,6 +8,11 @@ module FlowChat
     # When false, only the validation error message is shown to the user.
     mattr_accessor :combine_validation_error_with_message, default: true
 
+    # Session configuration object
+    def self.session
+      @session ||= SessionConfig.new
+    end
+
     # USSD-specific configuration object
     def self.ussd
       @ussd ||= UssdConfig.new
@@ -18,10 +23,29 @@ module FlowChat
       @whatsapp ||= WhatsappConfig.new
     end
 
+    class SessionConfig
+      attr_accessor :boundaries, :hash_phone_numbers, :identifier
+
+      def initialize
+        # Session boundaries control how session IDs are constructed
+        # :flow = separate sessions per flow
+        # :gateway = separate sessions per gateway
+        # :platform = separate sessions per platform (ussd, whatsapp)
+        @boundaries = [:flow, :gateway, :platform]
+        
+        # Always hash phone numbers for privacy
+        @hash_phone_numbers = true
+        
+        # Session identifier type (nil = let platforms choose their default)
+        # :msisdn = durable sessions (durable across timeouts)
+        # :request_id = ephemeral sessions (new session each time)
+        @identifier = nil
+      end
+    end
+
     class UssdConfig
       attr_accessor :pagination_page_size, :pagination_back_option, :pagination_back_text,
-        :pagination_next_option, :pagination_next_text,
-        :resumable_sessions_enabled, :resumable_sessions_global, :resumable_sessions_timeout_seconds
+        :pagination_next_option, :pagination_next_text
 
       def initialize
         @pagination_page_size = 140
@@ -29,9 +53,6 @@ module FlowChat
         @pagination_back_text = "Back"
         @pagination_next_option = "#"
         @pagination_next_text = "More"
-        @resumable_sessions_enabled = false
-        @resumable_sessions_global = true
-        @resumable_sessions_timeout_seconds = 300
       end
     end
 
@@ -68,4 +89,9 @@ module FlowChat
       end
     end
   end
+
+  # Shorthand for accessing the logger throughout the application
+  def self.logger
+    Config.logger
+  end
 end

data/lib/flow_chat/context.rb

@@ -1,26 +1,38 @@
 module FlowChat
   class Context
+    include FlowChat::Instrumentation
+
     def initialize
       @data = {}.with_indifferent_access
+
+      # Use instrumentation for context creation
+      self.class.instrument(Events::CONTEXT_CREATED, {
+        gateway: @data["request.gateway"]
+      })
     end
 
     def [](key)
-      @data[key]
+      value = @data[key]
+      FlowChat.logger.debug { "Context: Getting '#{key}' = #{value.inspect}" } if key != "session.store" # Avoid logging session store object
+      value
     end
 
     def []=(key, value)
+      FlowChat.logger.debug { "Context: Setting '#{key}' = #{value.inspect}" } if key != "session.store" && key != "controller" # Avoid logging large objects
       @data[key] = value
     end
 
     def input = @data["request.input"]
 
     def input=(value)
+      FlowChat.logger.debug { "Context: Setting input = '#{value}'" }
       @data["request.input"] = value
     end
 
     def session = @data["session"]
 
     def session=(value)
+      FlowChat.logger.debug { "Context: Setting session = #{value.class.name}" }
       @data["session"] = value
     end
 

data/lib/flow_chat/instrumentation/log_subscriber.rb

@@ -0,0 +1,176 @@
+module FlowChat
+  module Instrumentation
+    class LogSubscriber
+      # Flow execution events
+      def flow_execution_start(event)
+        payload = event.payload
+        FlowChat.logger.info { "Flow Execution Started: #{payload[:flow_name]}##{payload[:action]} [Session: #{payload[:session_id]}]" }
+      end
+
+      def flow_execution_end(event)
+        payload = event.payload
+        duration = event.duration.round(2)
+        FlowChat.logger.info { "Flow Execution Completed: #{payload[:flow_name]}##{payload[:action]} (#{duration}ms) [Session: #{payload[:session_id]}]" }
+      end
+
+      def flow_execution_error(event)
+        payload = event.payload
+        duration = event.duration.round(2)
+        FlowChat.logger.error { "Flow Execution Failed: #{payload[:flow_name]}##{payload[:action]} (#{duration}ms) - #{payload[:error_class]}: #{payload[:error_message]} [Session: #{payload[:session_id]}]" }
+      end
+
+      # Session events
+      def session_created(event)
+        payload = event.payload
+        FlowChat.logger.info { "Session Created: #{payload[:session_id]} [Store: #{payload[:store_type]}, Gateway: #{payload[:gateway]}]" }
+      end
+
+      def session_destroyed(event)
+        payload = event.payload
+        FlowChat.logger.info { "Session Destroyed: #{payload[:session_id]} [Gateway: #{payload[:gateway]}]" }
+      end
+
+      def session_cache_hit(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Session Cache Hit: #{payload[:session_id]} - Key: #{payload[:key]}" }
+      end
+
+      def session_cache_miss(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Session Cache Miss: #{payload[:session_id]} - Key: #{payload[:key]}" }
+      end
+
+      def session_data_set(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Session Data Set: #{payload[:session_id]} - Key: #{payload[:key]}" }
+      end
+
+      def session_data_get(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Session Data Get: #{payload[:session_id]} - Key: #{payload[:key]} = #{payload[:value].inspect}" }
+      end
+
+      # Middleware events
+      def middleware_before(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Middleware Before: #{payload[:middleware_name]} [Session: #{payload[:session_id]}]" }
+      end
+
+      def middleware_after(event)
+        payload = event.payload
+        duration = event.duration.round(2)
+        FlowChat.logger.debug { "Middleware After: #{payload[:middleware_name]} (#{duration}ms) [Session: #{payload[:session_id]}]" }
+      end
+
+      # Platform-agnostic events (new scalable approach)
+      def message_received(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+
+        case platform.to_sym
+        when :whatsapp
+          contact_info = payload[:contact_name] ? " (#{payload[:contact_name]})" : ""
+          FlowChat.logger.info { "#{platform_name} Message Received: #{payload[:from]}#{contact_info} - Type: #{payload[:message_type]} [ID: #{payload[:message_id]}]" }
+        when :ussd
+          FlowChat.logger.info { "#{platform_name} Message Received: #{payload[:from]} - Input: '#{payload[:message]}' [Session: #{payload[:session_id]}]" }
+        else
+          FlowChat.logger.info { "#{platform_name} Message Received: #{payload[:from]} - Message: '#{payload[:message]}' [Session: #{payload[:session_id]}]" }
+        end
+      end
+
+      def message_sent(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        duration = event.duration.round(2)
+
+        case platform.to_sym
+        when :whatsapp
+          FlowChat.logger.info { "#{platform_name} Message Sent: #{payload[:to]} - Type: #{payload[:message_type]} (#{duration}ms) [Length: #{payload[:content_length]} chars]" }
+        when :ussd
+          FlowChat.logger.info { "#{platform_name} Message Sent: #{payload[:to]} - Type: #{payload[:message_type]} (#{duration}ms) [Session: #{payload[:session_id]}]" }
+        else
+          FlowChat.logger.info { "#{platform_name} Message Sent: #{payload[:to]} - Type: #{payload[:message_type]} (#{duration}ms)" }
+        end
+      end
+
+      def webhook_verified(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        FlowChat.logger.info { "#{platform_name} Webhook Verified Successfully [Challenge: #{payload[:challenge]}]" }
+      end
+
+      def webhook_failed(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        FlowChat.logger.warn { "#{platform_name} Webhook Verification Failed: #{payload[:reason]}" }
+      end
+
+      def media_upload(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        duration = event.duration.round(2)
+
+        if payload[:success] != false  # Check for explicit false, not just falsy
+          FlowChat.logger.info { "#{platform_name} Media Upload: #{payload[:filename]} (#{format_bytes(payload[:size])}, #{duration}ms) - Success" }
+        else
+          FlowChat.logger.error { "#{platform_name} Media Upload Failed: #{payload[:filename]} (#{duration}ms) - #{payload[:error]}" }
+        end
+      end
+
+      def pagination_triggered(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        FlowChat.logger.info { "#{platform_name} Pagination Triggered: Page #{payload[:current_page]}/#{payload[:total_pages]} (#{payload[:content_length]} chars) [Session: #{payload[:session_id]}]" }
+      end
+
+      def api_request(event)
+        payload = event.payload
+        platform = payload[:platform] || "unknown"
+        platform_name = format_platform_name(platform)
+        duration = event.duration.round(2)
+
+        if payload[:success]
+          FlowChat.logger.debug { "#{platform_name} API Request: #{payload[:method]} #{payload[:endpoint]} (#{duration}ms) - Success" }
+        else
+          FlowChat.logger.error { "#{platform_name} API Request: #{payload[:method]} #{payload[:endpoint]} (#{duration}ms) - Failed: #{payload[:status]} #{payload[:error]}" }
+        end
+      end
+
+      # Context events
+      def context_created(event)
+        payload = event.payload
+        FlowChat.logger.debug { "Context Created [Gateway: #{payload[:gateway] || "unknown"}]" }
+      end
+
+      private
+
+      # Format platform name for display
+      def format_platform_name(platform)
+        case platform.to_sym
+        when :whatsapp then "WhatsApp"
+        when :ussd then "USSD"
+        else platform.to_s.capitalize
+        end
+      end
+
+      # Format bytes in a human-readable way
+      def format_bytes(bytes)
+        return "unknown size" unless bytes
+
+        if bytes < 1024
+          "#{bytes} bytes"
+        elsif bytes < 1024 * 1024
+          "#{(bytes / 1024.0).round(1)} KB"
+        else
+          "#{(bytes / (1024.0 * 1024.0)).round(1)} MB"
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/instrumentation/metrics_collector.rb

@@ -0,0 +1,197 @@
+module FlowChat
+  module Instrumentation
+    class MetricsCollector
+      attr_reader :metrics
+
+      def initialize
+        @metrics = {}
+        @mutex = Mutex.new
+        subscribe_to_events
+      end
+
+      # Get current metrics snapshot
+      def snapshot
+        @mutex.synchronize { @metrics.dup }
+      end
+
+      # Reset all metrics
+      def reset!
+        @mutex.synchronize { @metrics.clear }
+      end
+
+      # Get metrics for a specific category
+      def get_category(category)
+        @mutex.synchronize do
+          @metrics.select { |key, _| key.to_s.start_with?("#{category}.") }
+        end
+      end
+
+      private
+
+      def subscribe_to_events
+        # Flow execution metrics
+        ActiveSupport::Notifications.subscribe("flow.execution.end.flow_chat") do |event|
+          increment_counter("flows.executed")
+          track_timing("flows.execution_time", event.duration)
+          increment_counter("flows.by_name.#{event.payload[:flow_name]}")
+        end
+
+        ActiveSupport::Notifications.subscribe("flow.execution.error.flow_chat") do |event|
+          increment_counter("flows.errors")
+          increment_counter("flows.errors.by_class.#{event.payload[:error_class]}")
+          increment_counter("flows.errors.by_flow.#{event.payload[:flow_name]}")
+        end
+
+        # Session metrics
+        ActiveSupport::Notifications.subscribe("session.created.flow_chat") do |event|
+          increment_counter("sessions.created")
+          increment_counter("sessions.created.by_gateway.#{event.payload[:gateway]}")
+        end
+
+        ActiveSupport::Notifications.subscribe("session.destroyed.flow_chat") do |event|
+          increment_counter("sessions.destroyed")
+        end
+
+        ActiveSupport::Notifications.subscribe("session.cache.hit.flow_chat") do |event|
+          increment_counter("sessions.cache.hits")
+        end
+
+        ActiveSupport::Notifications.subscribe("session.cache.miss.flow_chat") do |event|
+          increment_counter("sessions.cache.misses")
+        end
+
+        ActiveSupport::Notifications.subscribe("session.data.get.flow_chat") do |event|
+          increment_counter("sessions.data.get")
+        end
+
+        ActiveSupport::Notifications.subscribe("session.data.set.flow_chat") do |event|
+          increment_counter("sessions.data.set")
+        end
+
+        ActiveSupport::Notifications.subscribe("message.received.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          increment_counter("#{platform}.messages.received")
+          if event.payload[:message_type]
+            increment_counter("#{platform}.messages.received.by_type.#{event.payload[:message_type]}")
+          end
+        end
+
+        ActiveSupport::Notifications.subscribe("message.sent.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          increment_counter("#{platform}.messages.sent")
+          if event.payload[:message_type]
+            increment_counter("#{platform}.messages.sent.by_type.#{event.payload[:message_type]}")
+          end
+          track_timing("#{platform}.api.response_time", event.duration)
+        end
+
+        ActiveSupport::Notifications.subscribe("webhook.verified.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          increment_counter("#{platform}.webhook.verified")
+        end
+
+        ActiveSupport::Notifications.subscribe("webhook.failed.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          increment_counter("#{platform}.webhook.failures")
+          if event.payload[:reason]
+            increment_counter("#{platform}.webhook.failures.by_reason.#{event.payload[:reason]}")
+          end
+        end
+
+        ActiveSupport::Notifications.subscribe("media.upload.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          if event.payload[:success] != false
+            increment_counter("#{platform}.media.uploads.success")
+            if event.payload[:size]
+              track_histogram("#{platform}.media.upload_size", event.payload[:size])
+            end
+          else
+            increment_counter("#{platform}.media.uploads.failure")
+          end
+          track_timing("#{platform}.media.upload_time", event.duration)
+        end
+
+        ActiveSupport::Notifications.subscribe("pagination.triggered.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          increment_counter("#{platform}.pagination.triggered")
+          if event.payload[:content_length]
+            track_histogram("#{platform}.pagination.content_length", event.payload[:content_length])
+          end
+        end
+
+        ActiveSupport::Notifications.subscribe("api.request.flow_chat") do |event|
+          platform = event.payload[:platform] || "unknown"
+          if event.payload[:success]
+            increment_counter("#{platform}.api.requests.success")
+          else
+            increment_counter("#{platform}.api.requests.failure")
+            if event.payload[:status]
+              increment_counter("#{platform}.api.requests.failure.by_status.#{event.payload[:status]}")
+            end
+          end
+          track_timing("#{platform}.api.request_time", event.duration)
+        end
+      end
+
+      def increment_counter(key, value = 1)
+        @mutex.synchronize do
+          @metrics[key] ||= 0
+          @metrics[key] += value
+        end
+      end
+
+      def track_timing(key, duration_ms)
+        timing_key = "#{key}.timings"
+        @mutex.synchronize do
+          @metrics[timing_key] ||= []
+          @metrics[timing_key] << duration_ms
+
+          # Keep only last 1000 measurements for memory efficiency
+          @metrics[timing_key] = @metrics[timing_key].last(1000) if @metrics[timing_key].size > 1000
+
+          # Calculate and store aggregates
+          timings = @metrics[timing_key]
+          @metrics["#{key}.avg"] = timings.sum / timings.size
+          @metrics["#{key}.min"] = timings.min
+          @metrics["#{key}.max"] = timings.max
+          @metrics["#{key}.p50"] = percentile(timings, 50)
+          @metrics["#{key}.p95"] = percentile(timings, 95)
+          @metrics["#{key}.p99"] = percentile(timings, 99)
+        end
+      end
+
+      def track_histogram(key, value)
+        histogram_key = "#{key}.histogram"
+        @mutex.synchronize do
+          @metrics[histogram_key] ||= []
+          @metrics[histogram_key] << value
+
+          # Keep only last 1000 measurements
+          @metrics[histogram_key] = @metrics[histogram_key].last(1000) if @metrics[histogram_key].size > 1000
+
+          # Calculate aggregates
+          values = @metrics[histogram_key]
+          @metrics["#{key}.total"] = values.sum
+          @metrics["#{key}.avg"] = values.sum / values.size
+          @metrics["#{key}.min"] = values.min
+          @metrics["#{key}.max"] = values.max
+        end
+      end
+
+      def percentile(array, percentile)
+        return nil if array.empty?
+
+        sorted = array.sort
+        k = (percentile / 100.0) * (sorted.length - 1)
+        f = k.floor
+        c = k.ceil
+
+        return sorted[k] if f == c
+
+        d0 = sorted[f] * (c - k)
+        d1 = sorted[c] * (k - f)
+        d0 + d1
+      end
+    end
+  end
+end

data/lib/flow_chat/instrumentation/setup.rb

@@ -0,0 +1,155 @@
+module FlowChat
+  module Instrumentation
+    module Setup
+      class << self
+        attr_accessor :log_subscriber, :metrics_collector
+
+        # Initialize instrumentation with default subscribers
+        def initialize!
+          setup_log_subscriber if FlowChat::Config.logger
+          setup_metrics_collector
+
+          FlowChat.logger&.info { "FlowChat::Instrumentation: Initialized with logging and metrics collection" }
+        end
+
+        # Set up both logging and metrics collection
+        def setup_instrumentation!(options = {})
+          setup_logging!(options)
+          setup_metrics!(options)
+        end
+
+        # Set up logging (LogSubscriber)
+        def setup_logging!(options = {})
+          return if @log_subscriber_setup
+
+          require_relative "log_subscriber"
+          setup_log_subscriber(options)
+          @log_subscriber_setup = true
+        end
+
+        # Set up metrics collection (MetricsCollector)
+        def setup_metrics!(options = {})
+          return if @metrics_collector_setup
+
+          require_relative "metrics_collector"
+          setup_metrics_collector(options)
+          @metrics_collector_setup = true
+        end
+
+        # Cleanup all subscribers
+        def cleanup!
+          @log_subscriber = nil
+          @metrics_collector = nil
+
+          # Note: ActiveSupport::Notifications doesn't provide an easy way to
+          # unsubscribe all subscribers, so this is mainly for reference cleanup
+          FlowChat.logger&.info { "FlowChat::Instrumentation: Cleaned up instrumentation" }
+        end
+
+        # Get current metrics (thread-safe)
+        def metrics
+          @metrics_collector&.snapshot || {}
+        end
+
+        # Reset metrics
+        def reset_metrics!
+          @metrics_collector&.reset!
+        end
+
+        # Subscribe to custom events
+        def subscribe(event_pattern, &block)
+          ActiveSupport::Notifications.subscribe(event_pattern, &block)
+        end
+
+        # Instrument a one-off event
+        def instrument(event_name, payload = {}, &block)
+          full_event_name = "#{event_name}.flow_chat"
+
+          enriched_payload = {
+            timestamp: Time.current
+          }.merge(payload).compact
+
+          ActiveSupport::Notifications.instrument(full_event_name, enriched_payload, &block)
+        end
+
+        # Access the metrics collector instance
+        def metrics_collector
+          @metrics_collector ||= FlowChat::Instrumentation::MetricsCollector.new
+        end
+
+        # Reset instrumentation (useful for testing)
+        def reset!
+          @log_subscriber_setup = false
+          @metrics_collector_setup = false
+          @log_subscriber = nil
+          @metrics_collector = nil
+        end
+
+        private
+
+        def setup_log_subscriber(options = {})
+          # Check if Rails is available and use its initialization callback
+          if defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+            Rails.application.config.after_initialize do
+              initialize_log_subscriber
+            end
+          else
+            # Initialize immediately for non-Rails environments
+            initialize_log_subscriber
+          end
+        end
+
+        def initialize_log_subscriber
+          return if @log_subscriber
+
+          @log_subscriber = FlowChat::Instrumentation::LogSubscriber.new
+
+          # Manually subscribe to all FlowChat events
+          subscribe_to_events
+        end
+
+        def subscribe_to_events
+          # Core framework events
+          subscribe_event("flow.execution.start.flow_chat", :flow_execution_start)
+          subscribe_event("flow.execution.end.flow_chat", :flow_execution_end)
+          subscribe_event("flow.execution.error.flow_chat", :flow_execution_error)
+
+          # Session events
+          subscribe_event("session.created.flow_chat", :session_created)
+          subscribe_event("session.destroyed.flow_chat", :session_destroyed)
+          subscribe_event("session.data.get.flow_chat", :session_data_get)
+          subscribe_event("session.data.set.flow_chat", :session_data_set)
+          subscribe_event("session.cache.hit.flow_chat", :session_cache_hit)
+          subscribe_event("session.cache.miss.flow_chat", :session_cache_miss)
+
+          # Platform-agnostic events (new scalable approach)
+          subscribe_event("message.received.flow_chat", :message_received)
+          subscribe_event("message.sent.flow_chat", :message_sent)
+          subscribe_event("webhook.verified.flow_chat", :webhook_verified)
+          subscribe_event("webhook.failed.flow_chat", :webhook_failed)
+          subscribe_event("api.request.flow_chat", :api_request)
+          subscribe_event("media.upload.flow_chat", :media_upload)
+          subscribe_event("pagination.triggered.flow_chat", :pagination_triggered)
+
+          # Middleware events
+          subscribe_event("middleware.before.flow_chat", :middleware_before)
+          subscribe_event("middleware.after.flow_chat", :middleware_after)
+
+          # Context events
+          subscribe_event("context.created.flow_chat", :context_created)
+        end
+
+        def subscribe_event(event_name, method_name)
+          ActiveSupport::Notifications.subscribe(event_name) do |*args|
+            event = ActiveSupport::Notifications::Event.new(*args)
+            @log_subscriber.send(method_name, event) if @log_subscriber.respond_to?(method_name)
+          end
+        end
+
+        def setup_metrics_collector(options = {})
+          @metrics_collector = FlowChat::Instrumentation::MetricsCollector.new
+        end
+      end
+    end
+  end
+end