flow_chat 0.7.0 → 0.8.1

data/lib/flow_chat/base_executor.rb

@@ -0,0 +1,57 @@
+module FlowChat
+  class BaseExecutor
+    def initialize(app)
+      @app = app
+      FlowChat.logger.debug { "#{log_prefix}: Initialized #{platform_name} executor middleware" }
+    end
+
+    def call(context)
+      flow_class = context.flow
+      action = context["flow.action"]
+      session_id = context["session.id"]
+
+      FlowChat.logger.info { "#{log_prefix}: Executing flow #{flow_class.name}##{action} for session #{session_id}" }
+
+      platform_app = build_platform_app(context)
+      FlowChat.logger.debug { "#{log_prefix}: #{platform_name} app built for flow execution" }
+
+      flow = flow_class.new platform_app
+      FlowChat.logger.debug { "#{log_prefix}: Flow instance created, invoking #{action} method" }
+
+      flow.send action
+      FlowChat.logger.warn { "#{log_prefix}: Flow execution failed to interact with user for #{flow_class.name}##{action}" }
+      raise FlowChat::Interrupt::Terminate, "Unexpected end of flow."
+    rescue FlowChat::Interrupt::RestartFlow => e
+      FlowChat.logger.info { "#{log_prefix}: Flow restart requested - Session: #{session_id}, restarting #{action}" }
+      retry
+    rescue FlowChat::Interrupt::Prompt => e
+      FlowChat.logger.info { "#{log_prefix}: Flow prompted user - Session: #{session_id}, Prompt: '#{e.prompt&.truncate(100)}'" }
+      FlowChat.logger.debug { "#{log_prefix}: Prompt details - Choices: #{e.choices&.size || 0}, Has media: #{!e.media.nil?}" }
+      [:prompt, e.prompt, e.choices, e.media]
+    rescue FlowChat::Interrupt::Terminate => e
+      FlowChat.logger.info { "#{log_prefix}: Flow terminated - Session: #{session_id}, Message: '#{e.prompt&.truncate(100)}'" }
+      FlowChat.logger.debug { "#{log_prefix}: Destroying session #{session_id}" }
+      context.session.destroy
+      [:terminate, e.prompt, nil, e.media]
+    rescue => error
+      FlowChat.logger.error { "#{log_prefix}: Flow execution failed - #{flow_class.name}##{action}, Session: #{session_id}, Error: #{error.class.name}: #{error.message}" }
+      FlowChat.logger.debug { "#{log_prefix}: Stack trace: #{error.backtrace.join("\n")}" }
+      raise
+    end
+
+    protected
+
+    # Subclasses must implement these methods
+    def platform_name
+      raise NotImplementedError, "Subclasses must implement platform_name"
+    end
+
+    def log_prefix
+      raise NotImplementedError, "Subclasses must implement log_prefix"
+    end
+
+    def build_platform_app(context)
+      raise NotImplementedError, "Subclasses must implement build_platform_app"
+    end
+  end
+end 

data/lib/flow_chat/base_processor.rb

@@ -13,6 +13,7 @@ module FlowChat
       @context["controller"] = controller
       @context["enable_simulator"] = enable_simulator.nil? ? (defined?(Rails) && Rails.env.local?) : enable_simulator
       @middleware = ::Middleware::Builder.new(name: middleware_name)
+      @session_options = FlowChat::Config.session
 
       FlowChat.logger.debug { "BaseProcessor: Simulator mode #{@context["enable_simulator"] ? "enabled" : "disabled"}" }
 
@@ -29,17 +30,46 @@ module FlowChat
     end
 
     def use_session_store(session_store)
-      FlowChat.logger.debug { "BaseProcessor: Configuring session store #{session_store.class.name}" }
+      raise "Session store must be a class" unless session_store.is_a?(Class)
+      FlowChat.logger.debug { "BaseProcessor: Configuring session store #{session_store.name}" }
       @context["session.store"] = session_store
       self
     end
 
+    def use_session_config(boundaries: nil, hash_phone_numbers: nil, identifier: nil)
+      FlowChat.logger.debug { "BaseProcessor: Configuring session config: boundaries=#{boundaries.inspect}, hash_phone_numbers=#{hash_phone_numbers}, identifier=#{identifier}" }
+      
+      # Update the session options directly
+      @session_options = @session_options.dup
+      @session_options.boundaries = Array(boundaries) if boundaries
+      @session_options.hash_phone_numbers = hash_phone_numbers if hash_phone_numbers
+      @session_options.identifier = identifier if identifier
+      
+      self
+    end
+
     def use_middleware(middleware)
-      FlowChat.logger.debug { "BaseProcessor: Adding middleware #{middleware.class.name}" }
+      raise "Middleware must be a class" unless middleware.is_a?(Class)
+      FlowChat.logger.debug { "BaseProcessor: Adding middleware #{middleware.name}" }
       @middleware.use middleware
       self
     end
 
+    def use_cross_platform_sessions
+      FlowChat.logger.debug { "BaseProcessor: Enabling cross-platform sessions via session configuration" }
+      use_session_config(
+        boundaries: [:flow]
+      )
+      self
+    end
+
+    def use_url_isolation
+      FlowChat.logger.debug { "BaseProcessor: Enabling URL-based session isolation" }
+      current_boundaries = @session_options.boundaries.dup
+      current_boundaries << :url unless current_boundaries.include?(:url)
+      use_session_config(boundaries: current_boundaries)
+    end
+
     def run(flow_class, action)
       # Instrument flow execution (this will log via LogSubscriber)
       instrument(Events::FLOW_EXECUTION_START, {
@@ -101,6 +131,7 @@ module FlowChat
 
       ::Middleware::Builder.new(name: name) do |b|
         b.use @gateway_class, *@gateway_args
+        b.use FlowChat::Session::Middleware, @session_options
         configure_middleware_stack(b)
       end.inject_logger(FlowChat.logger)
     end

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
 

data/lib/flow_chat/instrumentation/setup.rb

@@ -22,7 +22,6 @@ module FlowChat
         def setup_logging!(options = {})
           return if @log_subscriber_setup
 
-          require_relative "log_subscriber"
           setup_log_subscriber(options)
           @log_subscriber_setup = true
         end
@@ -31,7 +30,6 @@ module FlowChat
         def setup_metrics!(options = {})
           return if @metrics_collector_setup
 
-          require_relative "metrics_collector"
           setup_metrics_collector(options)
           @metrics_collector_setup = true
         end

data/lib/flow_chat/interrupt.rb

@@ -22,5 +22,11 @@ module FlowChat
     end
 
     class Terminate < Base; end
+
+    class RestartFlow < Base
+      def initialize
+        super("restart_flow")
+      end
+    end
   end
 end

data/lib/flow_chat/session/middleware.rb

@@ -5,8 +5,9 @@ module FlowChat
 
       attr_reader :context
 
-      def initialize(app)
+      def initialize(app, session_options)
         @app = app
+        @session_options = session_options
         FlowChat.logger.debug { "Session::Middleware: Initialized session middleware" }
       end
 
@@ -19,9 +20,10 @@ module FlowChat
         context.session = context["session.store"].new(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: context["session.store"].name,
+          store_type: store_type,
           gateway: context["request.gateway"]
         })
 
@@ -40,28 +42,111 @@ module FlowChat
 
       def session_id(context)
         gateway = context["request.gateway"]
+        platform = context["request.platform"]
         flow_name = context["flow.name"]
 
-        FlowChat.logger.debug { "Session::Middleware: Building session ID for gateway=#{gateway}, flow=#{flow_name}" }
+        # 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}" }
 
-        case gateway
-        when :whatsapp_cloud_api
-          # For WhatsApp, use phone number + flow name for consistent sessions
+        # 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"]
-          session_id = "#{gateway}:#{flow_name}:#{phone}"
-          FlowChat.logger.debug { "Session::Middleware: WhatsApp session ID created for phone #{phone}" }
-          session_id
-        # 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
-          request_id = context["request.id"]
-          session_id = "#{gateway}:#{flow_name}:#{request_id}"
-          FlowChat.logger.debug { "Session::Middleware: Generic session ID created for request #{request_id}" }
-          session_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/simulator/controller.rb

@@ -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,7 +45,7 @@ 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",

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/app.rb

@@ -1,58 +1,6 @@
 module FlowChat
   module Ussd
-    class App
-      attr_reader :session, :input, :context, :navigation_stack
-
-      def initialize(context)
-        @context = context
-        @session = context.session
-        @input = context.input
-        @navigation_stack = []
-      end
-
-      def screen(key)
-        raise ArgumentError, "a block is expected" unless block_given?
-        raise ArgumentError, "screen has already been presented" if navigation_stack.include?(key)
-
-        navigation_stack << key
-        return session.get(key) if session.get(key).present?
-
-        prompt = FlowChat::Prompt.new input
-        @input = nil # input is being submitted to prompt so we clear it
-
-        value = yield prompt
-        session.set(key, value)
-        value
-      end
-
-      def say(msg, media: nil)
-        raise FlowChat::Interrupt::Terminate.new(msg)
-      end
-
-      # WhatsApp-specific data accessors (not supported in USSD)
-      def contact_name
-        nil
-      end
-
-      def message_id
-        context["request.message_id"]
-      end
-
-      def timestamp
-        context["request.timestamp"]
-      end
-
-      def location
-        nil
-      end
-
-      def media
-        nil
-      end
-
-      def phone_number
-        context["request.msisdn"]
-      end
+    class App < FlowChat::BaseApp
     end
   end
 end

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

@@ -20,6 +20,7 @@ module FlowChat
           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

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

@@ -22,6 +22,7 @@ module FlowChat
 
           # Set a basic message_id (can be enhanced based on actual Nsano implementation)
           context["request.message_id"] = SecureRandom.uuid
+          context["request.platform"] = :ussd
 
           # TODO: Implement Nsano-specific parameter parsing
           # For now, add basic instrumentation structure for when this is implemented
@@ -58,7 +59,7 @@ module FlowChat
           #   if params["network"].present? && params["UserSessionID"].present?
           #     request_id = "nsano::request_id::#{params["UserSessionID"]}"
           #     context["ussd.request"] = {
-          #       provider: :nsano,
+          #       gateway: :nsano,
           #       network: params["network"].to_sym,
           #       msisdn: Phonelib.parse(params["msisdn"]).e164,
           #       type: Config.cache&.read(request_id).present? ? :response : :initial,
@@ -70,7 +71,7 @@ module FlowChat
 
           # status, headers, response = @app.call(context)
 
-          # if context["ussd.response"].present? && context["ussd.request"][:provider] == :nsano
+          # if context["ussd.response"].present? && context["ussd.request"][:gateway] == :nsano
           #   if context["ussd.response"][:type] == :terminal
           #     Config.cache&.write(request_id, nil)
           #   else

data/lib/flow_chat/ussd/middleware/executor.rb

@@ -1,47 +1,21 @@
+require_relative "../../base_executor"
+
 module FlowChat
   module Ussd
     module Middleware
-      class Executor
-        def initialize(app)
-          @app = app
-          FlowChat.logger.debug { "Ussd::Executor: Initialized USSD executor middleware" }
-        end
-
-        def call(context)
-          flow_class = context.flow
-          action = context["flow.action"]
-          session_id = context["session.id"]
-
-          FlowChat.logger.info { "Ussd::Executor: Executing flow #{flow_class.name}##{action} for session #{session_id}" }
+      class Executor < FlowChat::BaseExecutor
+        protected
 
-          ussd_app = build_ussd_app context
-          FlowChat.logger.debug { "Ussd::Executor: USSD app built for flow execution" }
-
-          flow = flow_class.new ussd_app
-          FlowChat.logger.debug { "Ussd::Executor: Flow instance created, invoking #{action} method" }
-
-          flow.send action
-          FlowChat.logger.warn { "Ussd::Executor: Flow execution failed to interact with user for #{flow_class.name}##{action}" }
-          raise FlowChat::Interrupt::Terminate, "Unexpected end of flow."
-        rescue FlowChat::Interrupt::Prompt => e
-          FlowChat.logger.info { "Ussd::Executor: Flow prompted user - Session: #{session_id}, Prompt: '#{e.prompt.truncate(100)}'" }
-          FlowChat.logger.debug { "Ussd::Executor: Prompt details - Choices: #{e.choices&.size || 0}, Has media: #{!e.media.nil?}" }
-          [:prompt, e.prompt, e.choices, e.media]
-        rescue FlowChat::Interrupt::Terminate => e
-          FlowChat.logger.info { "Ussd::Executor: Flow terminated - Session: #{session_id}, Message: '#{e.prompt.truncate(100)}'" }
-          FlowChat.logger.debug { "Ussd::Executor: Destroying session #{session_id}" }
-          context.session.destroy
-          [:terminate, e.prompt, nil, e.media]
-        rescue => error
-          FlowChat.logger.error { "Ussd::Executor: Flow execution failed - #{flow_class.name}##{action}, Session: #{session_id}, Error: #{error.class.name}: #{error.message}" }
-          FlowChat.logger.debug { "Ussd::Executor: Stack trace: #{error.backtrace.join("\n")}" }
-          raise
+        def platform_name
+          "USSD"
         end
 
-        private
+        def log_prefix
+          "Ussd::Executor"
+        end
 
-        def build_ussd_app(context)
-          FlowChat.logger.debug { "Ussd::Executor: Building USSD app instance" }
+        def build_platform_app(context)
+          FlowChat.logger.debug { "#{log_prefix}: Building USSD app instance" }
           FlowChat::Ussd::App.new(context)
         end
       end

data/lib/flow_chat/ussd/processor.rb

@@ -1,10 +1,11 @@
 module FlowChat
   module Ussd
     class Processor < FlowChat::BaseProcessor
-      def use_resumable_sessions
-        FlowChat.logger.debug { "Ussd::Processor: Enabling resumable sessions middleware" }
-        middleware.insert_before 0, FlowChat::Ussd::Middleware::ResumableSession
-        self
+      def use_durable_sessions(cross_gateway: false)
+        FlowChat.logger.debug { "Ussd::Processor: Enabling durable sessions via session configuration" }
+        use_session_config(
+          identifier: :msisdn  # Use MSISDN for durable sessions
+        )
       end
 
       protected
@@ -21,9 +22,6 @@ module FlowChat
       def configure_middleware_stack(builder)
         FlowChat.logger.debug { "Ussd::Processor: Configuring USSD middleware stack" }
 
-        builder.use FlowChat::Session::Middleware
-        FlowChat.logger.debug { "Ussd::Processor: Added Session::Middleware" }
-
         builder.use FlowChat::Ussd::Middleware::Pagination
         FlowChat.logger.debug { "Ussd::Processor: Added Ussd::Middleware::Pagination" }
 

data/lib/flow_chat/version.rb

@@ -1,3 +1,3 @@
 module FlowChat
-  VERSION = "0.7.0"
+  VERSION = "0.8.1"
 end

data/lib/flow_chat/whatsapp/app.rb

@@ -1,53 +1,10 @@
 module FlowChat
   module Whatsapp
-    class App
-      attr_reader :session, :input, :context, :navigation_stack
-
-      def initialize(context)
-        @context = context
-        @session = context.session
-        @input = context.input
-        @navigation_stack = []
-      end
-
-      def screen(key)
-        raise ArgumentError, "a block is expected" unless block_given?
-        raise ArgumentError, "screen has already been presented" if navigation_stack.include?(key)
-
-        navigation_stack << key
-        return session.get(key) if session.get(key).present?
-
-        user_input = input
-        if session.get("$started_at$").nil?
-          session.set("$started_at$", Time.current.iso8601)
-          user_input = nil
-        end
-
-        prompt = FlowChat::Prompt.new user_input
-        @input = nil # input is being submitted to prompt so we clear it
-
-        value = yield prompt
-        session.set(key, value)
-        value
-      end
-
-      def say(msg, media: nil)
-        raise FlowChat::Interrupt::Terminate.new(msg, media: media)
-      end
-
-      # WhatsApp-specific data accessors (read-only)
+    class App < FlowChat::BaseApp
       def contact_name
         context["request.contact_name"]
       end
 
-      def message_id
-        context["request.message_id"]
-      end
-
-      def timestamp
-        context["request.timestamp"]
-      end
-
       def location
         context["request.location"]
       end
@@ -56,8 +13,16 @@ module FlowChat
         context["request.media"]
       end
 
-      def phone_number
-        context["request.msisdn"]
+      protected
+
+      # WhatsApp has special startup logic and supports media
+      def prepare_user_input
+        user_input = input
+        if session.get("$started_at$").nil?
+          session.set("$started_at$", Time.current.iso8601)
+          user_input = nil
+        end
+        user_input
       end
     end
   end