flow_chat 0.6.1 → 0.8.0

data/lib/flow_chat/instrumentation.rb

@@ -0,0 +1,70 @@
+require "active_support/notifications"
+
+module FlowChat
+  module Instrumentation
+    extend ActiveSupport::Concern
+
+    # Instrument a block of code with the given event name and payload
+    def instrument(event_name, payload = {}, &block)
+      enriched_payload = payload&.dup || {}
+      if respond_to?(:context) && context
+        enriched_payload[:session_id] = context["session.id"] if context["session.id"]
+        enriched_payload[:flow_name] = context["flow.name"] if context["flow.name"]
+        enriched_payload[:gateway] = context["request.gateway"] if context["request.gateway"]
+      end
+
+      self.class.instrument(event_name, enriched_payload, &block)
+    end
+
+    class_methods do
+      def instrument(event_name, payload = {}, &block)
+        FlowChat::Instrumentation.instrument(event_name, payload, &block)
+      end
+    end
+
+    # Module-level method for direct calls like FlowChat::Instrumentation.instrument
+    def self.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
+
+    # Predefined event names for consistency
+    module Events
+      # Core framework events
+      FLOW_EXECUTION_START = "flow.execution.start"
+      FLOW_EXECUTION_END = "flow.execution.end"
+      FLOW_EXECUTION_ERROR = "flow.execution.error"
+
+      # Context events
+      CONTEXT_CREATED = "context.created"
+
+      # Session events
+      SESSION_CREATED = "session.created"
+      SESSION_DESTROYED = "session.destroyed"
+      SESSION_DATA_GET = "session.data.get"
+      SESSION_DATA_SET = "session.data.set"
+      SESSION_CACHE_HIT = "session.cache.hit"
+      SESSION_CACHE_MISS = "session.cache.miss"
+
+      # Platform-agnostic messaging events
+      # Gateway/platform information is included in the payload
+      MESSAGE_RECEIVED = "message.received"
+      MESSAGE_SENT = "message.sent"
+      WEBHOOK_VERIFIED = "webhook.verified"
+      WEBHOOK_FAILED = "webhook.failed"
+      API_REQUEST = "api.request"
+      MEDIA_UPLOAD = "media.upload"
+
+      PAGINATION_TRIGGERED = "pagination.triggered"
+
+      # Middleware events
+      MIDDLEWARE_BEFORE = "middleware.before"
+      MIDDLEWARE_AFTER = "middleware.after"
+    end
+  end
+end

data/lib/flow_chat/prompt.rb

@@ -6,13 +6,9 @@ module FlowChat
       @user_input = input
     end
 
-    def ask(msg, choices: nil, convert: nil, validate: nil, transform: nil, media: nil)
-      # Validate media and choices compatibility
-      validate_media_choices_compatibility(media, choices)
-
+    def ask(msg, choices: nil, transform: nil, validate: nil, media: nil)
       if user_input.present?
         input = user_input
-        input = convert.call(input) if convert.present?
         validation_error = validate.call(input) if validate.present?
 
         if validation_error.present?
@@ -38,17 +34,18 @@ module FlowChat
       terminate! message, media: media
     end
 
-    def select(msg, choices, media: nil)
-      # Validate media and choices compatibility
-      validate_media_choices_compatibility(media, choices)
+    def select(msg, choices, media: nil, error_message: "Invalid selection:")
+      raise ArgumentError, "choices must be an array or hash" unless choices.is_a?(Array) || choices.is_a?(Hash)
 
-      choices, choices_prompt = build_select_choices choices
+      normalized_choices = normalize_choices(choices)
       ask(
         msg,
-        choices: choices_prompt,
-        convert: lambda { |choice| choice.to_i },
-        validate: lambda { |choice| "Invalid selection:" unless (1..choices.size).cover?(choice) },
-        transform: lambda { |choice| choices[choice - 1] },
+        choices: choices,
+        validate: lambda { |choice| error_message unless normalized_choices.key?(choice.to_s) },
+        transform: lambda do |choice|
+          choices = choices.keys if choices.is_a?(Hash)
+          choices.index_by { |choice| choice.to_s }[choice.to_s]
+        end,
         media: media
       )
     end
@@ -67,20 +64,23 @@ module FlowChat
       end
     end
 
-    def build_select_choices(choices)
+    def normalize_choices(choices)
       case choices
-      when Array
-        choices_prompt = choices.map.with_index { |c, i| [i + 1, c] }.to_h
+      when nil
+        nil
       when Hash
-        choices_prompt = choices.values.map.with_index { |c, i| [i + 1, c] }.to_h
-        choices = choices.keys
+        choices.map { |k, v| [k.to_s, v] }.to_h
+      when Array
+        choices.map { |c| [c.to_s, c] }.to_h
       else
         raise ArgumentError, "choices must be an array or hash"
       end
-      [choices, choices_prompt]
     end
 
     def prompt!(msg, choices: nil, media: nil)
+      validate_media_choices_compatibility(media, choices)
+
+      choices = normalize_choices(choices)
       raise FlowChat::Interrupt::Prompt.new(msg, choices: choices, media: media)
     end
 
@@ -88,4 +88,4 @@ module FlowChat
       raise FlowChat::Interrupt::Terminate.new(msg, media: media)
     end
   end
-end 
+end

data/lib/flow_chat/session/cache_session_store.rb

@@ -1,45 +1,101 @@
 module FlowChat
   module Session
     class CacheSessionStore
+      include FlowChat::Instrumentation
+
+      # Make context available for instrumentation enrichment
+      attr_reader :context
+
       def initialize(context, cache = nil)
         @context = context
         @cache = cache || FlowChat::Config.cache
 
         raise ArgumentError, "Cache is required. Set FlowChat::Config.cache or pass a cache instance." unless @cache
+
+        FlowChat.logger.debug { "CacheSessionStore: Initialized cache session store for session #{session_key}" }
+        FlowChat.logger.debug { "CacheSessionStore: Cache backend: #{@cache.class.name}" }
       end
 
       def get(key)
         return nil unless @context
 
+        FlowChat.logger.debug { "CacheSessionStore: Getting key '#{key}' from session #{session_key}" }
+
         data = @cache.read(session_key)
-        return nil unless data
+        session_id = @context["session.id"]
+
+        unless data
+          # Use instrumentation for cache miss
+          instrument(Events::SESSION_CACHE_MISS, {
+            session_id: session_id,
+            key: key.to_s
+          })
+          return nil
+        end
 
-        data[key.to_s]
+        value = data[key.to_s]
+
+        # Use instrumentation for cache hit and data get
+        instrument(Events::SESSION_CACHE_HIT, {
+          session_id: session_id,
+          key: key.to_s
+        })
+
+        instrument(Events::SESSION_DATA_GET, {
+          session_id: session_id,
+          key: key.to_s,
+          value: value
+        })
+
+        value
       end
 
       def set(key, value)
         return unless @context
 
+        FlowChat.logger.debug { "CacheSessionStore: Setting key '#{key}' = #{value.inspect} in session #{session_key}" }
+
         data = @cache.read(session_key) || {}
         data[key.to_s] = value
 
-        @cache.write(session_key, data, expires_in: session_ttl)
+        ttl = session_ttl
+        @cache.write(session_key, data, expires_in: ttl)
+
+        # Use instrumentation for data set
+        instrument(Events::SESSION_DATA_SET, {
+          session_id: @context["session.id"],
+          key: key.to_s
+        })
+
+        FlowChat.logger.debug { "CacheSessionStore: Session data saved with TTL #{ttl.inspect}" }
         value
       end
 
       def delete(key)
         return unless @context
 
+        FlowChat.logger.debug { "CacheSessionStore: Deleting key '#{key}' from session #{session_key}" }
+
         data = @cache.read(session_key)
-        return unless data
+        unless data
+          FlowChat.logger.debug { "CacheSessionStore: No session data found for deletion" }
+          return
+        end
 
         data.delete(key.to_s)
         @cache.write(session_key, data, expires_in: session_ttl)
+
+        FlowChat.logger.debug { "CacheSessionStore: Key '#{key}' deleted from session" }
       end
 
       def clear
         return unless @context
 
+        # Use instrumentation for session destruction
+        instrument(Events::SESSION_DESTROYED, {
+          session_id: @context["session.id"]
+        })
+
         @cache.delete(session_key)
       end
 
@@ -47,16 +103,20 @@ module FlowChat
       alias_method :destroy, :clear
 
       def exists?
-        @cache.exist?(session_key)
+        exists = @cache.exist?(session_key)
+        FlowChat.logger.debug { "CacheSessionStore: Session #{session_key} exists: #{exists}" }
+        exists
       end
 
       private
 
       def session_key
+        return "flow_chat:session:nil_context" unless @context
+
         gateway = @context["request.gateway"]
         msisdn = @context["request.msisdn"]
 
-        case gateway
+        key = case gateway
         when :whatsapp_cloud_api
           "flow_chat:session:whatsapp:#{msisdn}"
         when :nalo, :nsano
@@ -65,12 +125,15 @@ module FlowChat
         else
           "flow_chat:session:unknown:#{msisdn}"
         end
+
+        FlowChat.logger.debug { "CacheSessionStore: Generated session key: #{key}" }
+        key
       end
 
       def session_ttl
         gateway = @context["request.gateway"]
 
-        case gateway
+        ttl = case gateway
         when :whatsapp_cloud_api
           7.days  # WhatsApp conversations can be long-lived
         when :nalo, :nsano
@@ -78,6 +141,9 @@ module FlowChat
         else
           1.day   # Default
         end
+
+        FlowChat.logger.debug { "CacheSessionStore: Session TTL for #{gateway}: #{ttl.inspect}" }
+        ttl
       end
     end
   end

data/lib/flow_chat/session/middleware.rb

@@ -1,34 +1,152 @@
 module FlowChat
   module Session
     class Middleware
-      def initialize(app)
+      include FlowChat::Instrumentation
+
+      attr_reader :context
+
+      def initialize(app, session_options)
         @app = app
+        @session_options = session_options
+        FlowChat.logger.debug { "Session::Middleware: Initialized session middleware" }
       end
 
       def call(context)
-        context["session.id"] = session_id context
+        @context = context
+        session_id = session_id(context)
+        FlowChat.logger.debug { "Session::Middleware: Generated session ID: #{session_id}" }
+
+        context["session.id"] = session_id
         context.session = context["session.store"].new(context)
-        @app.call(context)
+
+        # Use instrumentation instead of direct logging for session creation
+        store_type = context["session.store"].name || "$Anonymous"
+        instrument(Events::SESSION_CREATED, {
+          session_id: session_id,
+          store_type: store_type,
+          gateway: context["request.gateway"]
+        })
+
+        FlowChat.logger.debug { "Session::Middleware: Session store: #{context["session.store"].class.name}" }
+
+        result = @app.call(context)
+
+        FlowChat.logger.debug { "Session::Middleware: Session processing completed for #{session_id}" }
+        result
+      rescue => error
+        FlowChat.logger.error { "Session::Middleware: Error in session processing for #{session_id}: #{error.class.name}: #{error.message}" }
+        raise
       end
 
       private
 
       def session_id(context)
         gateway = context["request.gateway"]
+        platform = context["request.platform"]
         flow_name = context["flow.name"]
-        case gateway
-        when :whatsapp_cloud_api
-          # For WhatsApp, use phone number + flow name for consistent sessions
+
+        # Check for explicit session ID first (for manual session management)
+        if context["session.id"].present?
+          session_id = context["session.id"]
+          FlowChat.logger.debug { "Session::Middleware: Using explicit session ID: #{session_id}" }
+          return session_id
+        end
+
+        FlowChat.logger.debug { "Session::Middleware: Building session ID for platform=#{platform}, gateway=#{gateway}, flow=#{flow_name}" }
+
+        # Get identifier based on configuration
+        identifier = get_session_identifier(context)
+
+        # Build session ID based on configuration
+        session_id = build_session_id(flow_name, platform, gateway, identifier)
+        FlowChat.logger.debug { "Session::Middleware: Generated session ID: #{session_id}" }
+        session_id
+      end
+
+      def get_session_identifier(context)
+        identifier_type = @session_options.identifier
+        
+        # If no identifier specified, use platform defaults
+        if identifier_type.nil?
+          platform = context["request.platform"]
+          identifier_type = case platform
+          when :ussd
+            :request_id    # USSD defaults to ephemeral sessions
+          when :whatsapp
+            :msisdn       # WhatsApp defaults to durable sessions
+          else
+            :msisdn       # Default fallback to durable
+          end
+        end
+        
+        case identifier_type
+        when :request_id
+          context["request.id"]
+        when :msisdn
           phone = context["request.msisdn"]
-          "#{gateway}:#{flow_name}:#{phone}"
-        # when :nalo, :nsano
-        #   # For USSD, use the request ID from the gateway
-        #   "#{gateway}:#{flow_name}:#{context["request.id"]}"
+          @session_options.hash_phone_numbers ? hash_phone_number(phone) : phone
         else
-          # Fallback to request ID
-          "#{gateway}:#{flow_name}:#{context["request.id"]}"
+          raise "Invalid session identifier type: #{identifier_type}"
         end
       end
+
+      def build_session_id(flow_name, platform, gateway, identifier)
+        parts = []
+
+        # Add flow name if flow isolation is enabled
+        parts << flow_name if @session_options.boundaries.include?(:flow)
+
+        # Add platform if platform isolation is enabled
+        parts << platform.to_s if @session_options.boundaries.include?(:platform)
+
+        # Add gateway if gateway isolation is enabled
+        parts << gateway.to_s if @session_options.boundaries.include?(:gateway)
+
+        # Add URL if URL isolation is enabled
+        if @session_options.boundaries.include?(:url)
+          url_identifier = get_url_identifier(context)
+          parts << url_identifier if url_identifier.present?
+        end
+
+        # Add the session identifier
+        parts << identifier if identifier.present?
+
+        # Join parts with colons
+        parts.join(":")
+      end
+
+      def get_url_identifier(context)
+        request = context.controller&.request
+        return nil unless request
+
+        # Extract host and path for URL boundary
+        host = request.host rescue nil
+        path = request.path rescue nil
+
+        # Create a normalized URL identifier: host + path 
+        # e.g., "example.com/api/v1/ussd" or "tenant1.example.com/ussd"
+        url_parts = []
+        url_parts << host if host.present?
+        url_parts << path.sub(/^\//, '') if path.present? && path != '/'
+
+        # For long URLs, use first part + hash suffix instead of full hash
+        url_identifier = url_parts.join('/').gsub(/[^a-zA-Z0-9._-]/, '_')
+        if url_identifier.length > 50
+          require 'digest'
+          # Take first 41 chars + hash suffix to keep it manageable but recognizable
+          first_part = url_identifier[0, 41]
+          hash_suffix = Digest::SHA256.hexdigest(url_identifier)[0, 8]
+          url_identifier = "#{first_part}_#{hash_suffix}"
+        end
+
+        url_identifier
+      end
+
+      def hash_phone_number(phone)
+        # Use SHA256 but only take first 8 characters for reasonable session IDs
+        require 'digest'
+        Digest::SHA256.hexdigest(phone.to_s)[0, 8]
+      end
     end
   end
 end

data/lib/flow_chat/session/rails_session_store.rb

@@ -1,27 +1,62 @@
 module FlowChat
   module Session
     class RailsSessionStore
+      include FlowChat::Instrumentation
+
+      # Make context available for instrumentation enrichment
+      attr_reader :context
+
       def initialize(context)
+        @context = context
         @session_id = context["session.id"]
         @session_store = context.controller.session
         @session_data = (session_store[session_id] || {}).with_indifferent_access
+
+        FlowChat.logger.debug { "RailsSessionStore: Initialized Rails session store for session #{session_id}" }
+        FlowChat.logger.debug { "RailsSessionStore: Loaded session data with #{session_data.keys.size} keys" }
       end
 
       def get(key)
-        session_data[key]
+        value = session_data[key]
+
+        # Use instrumentation for data get
+        instrument(Events::SESSION_DATA_GET, {
+          session_id: session_id,
+          key: key.to_s,
+          value: value
+        })
+
+        value
       end
 
       def set(key, value)
+        FlowChat.logger.debug { "RailsSessionStore: Setting key '#{key}' = #{value.inspect} in session #{session_id}" }
+
         session_data[key] = value
         session_store[session_id] = session_data
+
+        # Use instrumentation for data set
+        instrument(Events::SESSION_DATA_SET, {
+          session_id: session_id,
+          key: key.to_s
+        })
+
+        FlowChat.logger.debug { "RailsSessionStore: Session data saved to Rails session store" }
         value
       end
 
       def delete(key)
+        FlowChat.logger.debug { "RailsSessionStore: Deleting key '#{key}' from session #{session_id}" }
         set key, nil
       end
 
       def destroy
+        # Use instrumentation for session destruction
+        instrument(Events::SESSION_DESTROYED, {
+          session_id: session_id,
+          gateway: "rails" # Rails doesn't have a specific gateway context
+        })
+
         session_store[session_id] = nil
       end
 

data/lib/flow_chat/simulator/controller.rb

@@ -4,7 +4,7 @@ module FlowChat
       def flowchat_simulator
         # Set simulator cookie for authentication
         set_simulator_cookie
-        
+
         respond_to do |format|
           format.html do
             render inline: simulator_view_template, layout: false, locals: simulator_locals
@@ -32,7 +32,7 @@ module FlowChat
             name: "USSD (Nalo)",
             description: "USSD integration using Nalo",
             processor_type: "ussd",
-            provider: "nalo",
+            gateway: "nalo",
             endpoint: "/ussd",
             icon: "📱",
             color: "#28a745",
@@ -45,13 +45,13 @@ module FlowChat
             name: "WhatsApp (Cloud API)",
             description: "WhatsApp integration using Cloud API",
             processor_type: "whatsapp",
-            provider: "cloud_api",
+            gateway: "cloud_api",
             endpoint: "/whatsapp/webhook",
             icon: "💬",
             color: "#25D366",
             settings: {
               phone_number: default_phone_number,
-              contact_name: default_contact_name,
+              contact_name: default_contact_name
             }
           }
         }
@@ -78,18 +78,18 @@ module FlowChat
       def set_simulator_cookie
         # Get global simulator secret
         simulator_secret = FlowChat::Config.simulator_secret
-        
+
         unless simulator_secret && !simulator_secret.empty?
           raise StandardError, "Simulator secret not configured. Please set FlowChat::Config.simulator_secret to enable simulator mode."
         end
-        
+
         # Generate timestamp-based signed cookie
         timestamp = Time.now.to_i
         message = "simulator:#{timestamp}"
         signature = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), simulator_secret, message)
-        
+
         cookie_value = "#{timestamp}:#{signature}"
-        
+
         # Set secure cookie (valid for 24 hours)
         cookies[:flowchat_simulator] = {
           value: cookie_value,

data/lib/flow_chat/simulator/views/simulator.html.erb

@@ -1057,8 +1057,8 @@
             <span class="config-detail-value">${config.endpoint}</span>
           </div>
           <div class="config-detail-item">
-            <span class="config-detail-label">Provider:</span>
-            <span class="config-detail-value">${config.provider}</span>
+            <span class="config-detail-label">gateway:</span>
+            <span class="config-detail-value">${config.gateway}</span>
           </div>
           <div class="config-detail-item">
             <span class="config-detail-label">Type:</span>
@@ -1304,7 +1304,7 @@
         
         let requestData = {}
         
-        switch (config.provider) {
+        switch (config.gateway) {
           case 'nalo':
             requestData = {
               USERID: state.sessionId,
@@ -1322,7 +1322,7 @@
             }
             break
           default:
-            throw new Error(`Unsupported USSD provider: ${config.provider}`)
+            throw new Error(`Unsupported USSD gateway: ${config.gateway}`)
         }
         
         try {
@@ -1342,7 +1342,7 @@
             throw new Error(`HTTP ${response.status}: ${response.statusText}`)
           }
           
-          switch (config.provider) {
+          switch (config.gateway) {
             case 'nalo':
               displayUSSDResponse(data.MSG)
               state.isRunning = data.MSGTYPE

data/lib/flow_chat/ussd/gateway/nalo.rb

@@ -4,24 +4,55 @@ module FlowChat
   module Ussd
     module Gateway
       class Nalo
+        include FlowChat::Instrumentation
+
+        attr_reader :context
+
         def initialize(app)
           @app = app
         end
 
         def call(context)
+          @context = context
           params = context.controller.request.params
 
           context["request.id"] = params["USERID"]
           context["request.message_id"] = SecureRandom.uuid
           context["request.timestamp"] = Time.current.iso8601
           context["request.gateway"] = :nalo
+          context["request.platform"] = :ussd
           context["request.network"] = nil
           context["request.msisdn"] = Phonelib.parse(params["MSISDN"]).e164
           # context["request.type"] = params["MSGTYPE"] ? :initial : :response
           context.input = params["USERDATA"].presence
 
+          # Instrument message received when user provides input using new scalable approach
+          if context.input.present?
+            instrument(Events::MESSAGE_RECEIVED, {
+              from: context["request.msisdn"],
+              message: context.input,
+              session_id: context["request.id"],
+              gateway: :nalo,
+              platform: :ussd,
+              timestamp: context["request.timestamp"]
+            })
+          end
+
+          # Process the request and instrument the response
           type, prompt, choices, media = @app.call(context)
 
+          # Instrument message sent using new scalable approach
+          instrument(Events::MESSAGE_SENT, {
+            to: context["request.msisdn"],
+            session_id: context["request.id"],
+            message: context.input || "",
+            message_type: (type == :prompt) ? "prompt" : "terminal",
+            gateway: :nalo,
+            platform: :ussd,
+            content_length: prompt.to_s.length,
+            timestamp: context["request.timestamp"]
+          })
+
           context.controller.render json: {
             USERID: params["USERID"],
             MSISDN: params["MSISDN"],