flow_chat 0.8.0 → 0.8.2

data/examples/simulator_controller.rb

@@ -31,6 +31,15 @@ class SimulatorController < ApplicationController
         icon: "💬",
         color: "#25D366"
       },
+      http_main: {
+        name: "Main HTTP API",
+        description: "JSON HTTP API endpoint",
+        processor_type: "http",
+        gateway: "http_simple",
+        endpoint: "/http/webhook",
+        icon: "🌐",
+        color: "#0066cc"
+      },
       whatsapp_tenant_a: {
         name: "Tenant A WhatsApp",
         description: "Multi-tenant endpoint for Tenant A",
@@ -40,6 +49,15 @@ class SimulatorController < ApplicationController
         icon: "🏢",
         color: "#fd7e14"
       },
+      http_external: {
+        name: "External HTTP Test",
+        description: "Test with external HTTP server",
+        processor_type: "http",
+        gateway: "http_simple",
+        endpoint: "http://localhost:4567/http/webhook",
+        icon: "🔗",
+        color: "#17a2b8"
+      },
       whatsapp_legacy: {
         name: "Legacy WhatsApp",
         description: "Legacy endpoint for compatibility",
@@ -54,7 +72,7 @@ class SimulatorController < ApplicationController
 
   # Default configuration to start with
   def default_config_key
-    :whatsapp_main
+    :http_main
   end
 
   # Default test phone number
@@ -79,8 +97,10 @@ end
 # 5. View request/response logs in real-time
 
 # This allows you to test:
+# - Different protocol types (USSD, WhatsApp, HTTP)
 # - Different controller implementations on the same server
 # - Different API versions (v1, v2, etc.)
 # - Multi-tenant endpoints with different configurations
 # - Legacy endpoints alongside new ones
+# - External HTTP servers (run examples/http_simulator_test.rb)
 # - Different flow implementations for different endpoints

data/examples/ussd_controller.rb

@@ -237,7 +237,7 @@ class UssdController < ApplicationController
       # Or configure session boundaries explicitly:
       # config.use_session_config(
       #   boundaries: [:flow, :platform],     # which boundaries to enforce
-      #   hash_phone_numbers: true            # hash phone numbers for privacy
+      #   hash_identifiers: true            # hash phone numbers for privacy
       # )
     end
 

data/lib/flow_chat/base_app.rb

@@ -0,0 +1,86 @@
+module FlowChat
+  class BaseApp
+    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 = prepare_user_input
+      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 go_back
+      return false if navigation_stack.empty?
+      
+      @context.input = nil
+      current_screen = navigation_stack.last
+      session.delete(current_screen)
+      
+      # Restart the flow from the beginning
+      raise FlowChat::Interrupt::RestartFlow.new
+    end
+
+    def say(msg, media: nil)
+      raise FlowChat::Interrupt::Terminate.new(msg, media: media)
+    end
+
+    def platform
+      context["request.platform"]
+    end
+
+    def gateway
+      context["request.gateway"]
+    end
+    
+    def user_id
+      context["request.user_id"]
+    end
+
+    def msisdn
+      context["request.msisdn"]
+    end
+
+    def message_id
+      context["request.message_id"]
+    end
+
+    def timestamp
+      context["request.timestamp"]
+    end
+
+    def contact_name
+      nil
+    end
+
+    def location
+      nil
+    end
+
+    def media
+      nil
+    end
+
+    protected
+
+    # Platform-specific methods to be overridden
+    def prepare_user_input
+      input
+    end
+  end
+end 

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
+      [:terminal, 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

@@ -36,14 +36,14 @@ module FlowChat
       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}" }
+    def use_session_config(boundaries: nil, hash_identifiers: nil, identifier: nil)
+      FlowChat.logger.debug { "BaseProcessor: Configuring session config: boundaries=#{boundaries.inspect}, hash_identifiers=#{hash_identifiers}, 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
+      @session_options.boundaries = Array(boundaries) if boundaries != nil
+      @session_options.hash_identifiers = hash_identifiers if hash_identifiers != nil
+      @session_options.identifier = identifier if identifier != nil
       
       self
     end
@@ -70,7 +70,7 @@ module FlowChat
       use_session_config(boundaries: current_boundaries)
     end
 
-    def run(flow_class, action)
+    def run(flow_class, action, **options)
       # Instrument flow execution (this will log via LogSubscriber)
       instrument(Events::FLOW_EXECUTION_START, {
         flow_name: flow_class.name.underscore,
@@ -81,6 +81,7 @@ module FlowChat
       @context["flow.name"] = flow_class.name.underscore
       @context["flow.class"] = flow_class
       @context["flow.action"] = action
+      @context["flow.options"] = options
 
       FlowChat.logger.debug { "BaseProcessor: Context prepared for flow #{flow_class.name}" }
 

data/lib/flow_chat/config.rb

@@ -23,8 +23,13 @@ module FlowChat
       @whatsapp ||= WhatsappConfig.new
     end
 
+    # HTTP-specific configuration object
+    def self.http
+      @http ||= HttpConfig.new
+    end
+
     class SessionConfig
-      attr_accessor :boundaries, :hash_phone_numbers, :identifier
+      attr_accessor :boundaries, :hash_identifiers, :identifier
 
       def initialize
         # Session boundaries control how session IDs are constructed
@@ -34,7 +39,7 @@ module FlowChat
         @boundaries = [:flow, :gateway, :platform]
         
         # Always hash phone numbers for privacy
-        @hash_phone_numbers = true
+        @hash_identifiers = true
         
         # Session identifier type (nil = let platforms choose their default)
         # :msisdn = durable sessions (durable across timeouts)
@@ -88,6 +93,16 @@ module FlowChat
         @message_handling_mode == :simulator
       end
     end
+
+    class HttpConfig
+      attr_accessor :default_gateway, :request_timeout, :response_format
+
+      def initialize
+        @default_gateway = :simple
+        @request_timeout = 30
+        @response_format = :json
+      end
+    end
   end
 
   # Shorthand for accessing the logger throughout the application

data/lib/flow_chat/http/app.rb

@@ -0,0 +1,6 @@
+module FlowChat
+  module Http
+    class App < FlowChat::BaseApp
+    end
+  end
+end 

data/lib/flow_chat/http/gateway/simple.rb

@@ -0,0 +1,77 @@
+module FlowChat
+  module Http
+    module Gateway
+      class Simple
+        include FlowChat::Instrumentation
+
+        attr_reader :context
+
+        def initialize(app)
+          @app = app
+        end
+
+        def call(context)
+          @context = context
+          params = context.controller.request.params
+          request = context.controller.request
+
+          # Extract basic request information
+          context["request.id"] = params["session_id"] || SecureRandom.uuid
+          context["request.msisdn"] = FlowChat::PhoneNumberUtil.to_e164(params["msisdn"])
+          context["request.user_id"] = params["user_id"] || context["request.msisdn"] || context["request.id"]
+          context["request.message_id"] = params["message_id"] || SecureRandom.uuid
+          context["request.timestamp"] = Time.current.iso8601
+          context["request.gateway"] = :http_simple
+          context["request.platform"] = :http
+          context["request.network"] = nil
+          context["request.method"] = request.method
+          context["request.path"] = request.path
+          context["request.user_agent"] = request.user_agent
+          context.input = params["input"] || params["message"]
+
+          # Instrument message received when user provides input
+          if context.input.present?
+            instrument(Events::MESSAGE_RECEIVED, {
+              from: context["request.user_id"],
+              message: context.input,
+              timestamp: context["request.timestamp"]
+            })
+          end
+
+          # Process the request
+          type, prompt, choices, media = @app.call(context)
+
+          # Instrument message sent
+          instrument(Events::MESSAGE_SENT, {
+            to: context["request.user_id"],
+            session_id: context["request.id"],
+            message: context.input || "",
+            message_type: (type == :prompt) ? "prompt" : "terminal",
+            gateway: :http_simple,
+            platform: :http,
+            content_length: prompt.to_s.length,
+            timestamp: context["request.timestamp"]
+          })
+
+          # Render response as JSON
+          response_data = render_response(type, prompt, choices, media)
+          context.controller.render json: response_data
+        end
+
+        private
+
+        def render_response(type, prompt, choices, media)
+          rendered = FlowChat::Http::Renderer.new(prompt, choices: choices, media: media).render
+          
+          {
+            type: type,
+            session_id: context["request.id"],
+            user_id: context["request.user_id"],
+            timestamp: context["request.timestamp"],
+            **rendered
+          }
+        end
+      end
+    end
+  end
+end 

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

@@ -0,0 +1,24 @@
+require_relative "../../base_executor"
+
+module FlowChat
+  module Http
+    module Middleware
+      class Executor < FlowChat::BaseExecutor
+        protected
+
+        def platform_name
+          "HTTP"
+        end
+
+        def log_prefix
+          "Http::Executor"
+        end
+
+        def build_platform_app(context)
+          FlowChat.logger.debug { "#{log_prefix}: Building HTTP app instance" }
+          FlowChat::Http::App.new(context)
+        end
+      end
+    end
+  end
+end 

data/lib/flow_chat/http/processor.rb

@@ -0,0 +1,33 @@
+module FlowChat
+  module Http
+    class Processor < FlowChat::BaseProcessor
+      def use_durable_sessions(cross_gateway: false)
+        FlowChat.logger.debug { "Http::Processor: Enabling durable sessions via session configuration" }
+        use_session_config(
+          identifier: :user_id
+        )
+      end
+
+      protected
+
+      def middleware_name
+        "http.middleware"
+      end
+
+      def build_middleware_stack
+        FlowChat.logger.debug { "Http::Processor: Building HTTP middleware stack" }
+        create_middleware_stack("http")
+      end
+
+      def configure_middleware_stack(builder)
+        FlowChat.logger.debug { "Http::Processor: Configuring HTTP middleware stack" }
+
+        builder.use middleware
+        FlowChat.logger.debug { "Http::Processor: Added custom middleware" }
+
+        builder.use FlowChat::Http::Middleware::Executor
+        FlowChat.logger.debug { "Http::Processor: Added Http::Middleware::Executor" }
+      end
+    end
+  end
+end 

data/lib/flow_chat/http/renderer.rb

@@ -0,0 +1,41 @@
+module FlowChat
+  module Http
+    class Renderer
+      attr_reader :prompt, :choices, :media
+
+      def initialize(prompt, choices: nil, media: nil)
+        @prompt = prompt
+        @choices = choices
+        @media = media
+      end
+
+      def render = build_response
+
+      private
+
+      def build_response
+        {
+          message: prompt,
+          choices: format_choices,
+          media: format_media
+        }.compact
+      end
+
+      def format_choices
+        return unless choices.present?
+
+        choices.map { |key, value| { key: key, value: value } }
+      end
+
+      def format_media
+        return unless media.present?
+
+        {
+          url: media[:url] || media[:path],
+          type: media[:type] || :image,
+          caption: media[:caption]
+        }.compact
+      end
+    end
+  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/instrumentation.rb

@@ -8,9 +8,11 @@ module FlowChat
     def instrument(event_name, payload = {}, &block)
       enriched_payload = payload&.dup || {}
       if respond_to?(:context) && context
+        enriched_payload[:request_id] = context["request.id"] if context["request.id"]
         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"]
+        enriched_payload[:platform] = context["request.platform"] if context["request.platform"]
       end
 
       self.class.instrument(event_name, enriched_payload, &block)

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

@@ -0,0 +1,47 @@
+module FlowChat
+  module PhoneNumberUtil
+    def self.to_e164(phone_number)
+      return phone_number if phone_number.nil? || phone_number.empty?
+      
+      begin
+        # Try to load phonelib without Rails dependency
+        require_phonelib_safely
+        Phonelib.parse(phone_number).e164
+      rescue => e
+        FlowChat.logger.warn { "PhoneNumberUtil: Failed to parse phone number '#{phone_number}': #{e.message}" }
+        # Fallback to simple formatting if phonelib fails
+        fallback_e164_format(phone_number)
+      end
+    end
+
+    private
+
+    def self.require_phonelib_safely
+      return if defined?(Phonelib)
+      
+      # Temporarily stub Rails if it doesn't exist
+      unless defined?(Rails)
+        stub_rails = Module.new do
+          def self.const_missing(name)
+            if name == :Railtie
+              Class.new
+            else
+              super
+            end
+          end
+        end
+        Object.const_set(:Rails, stub_rails)
+        require "phonelib"
+        Object.send(:remove_const, :Rails)
+      else
+        require "phonelib"
+      end
+    end
+
+    def self.fallback_e164_format(phone_number)
+      # Simple fallback - ensure it starts with + and looks like a phone number
+      cleaned = phone_number.to_s.gsub(/[^\d+]/, '')
+      cleaned.start_with?('+') ? cleaned : "+#{cleaned}"
+    end
+  end
+end 

data/lib/flow_chat/session/cache_session_store.rb

@@ -111,23 +111,7 @@ module FlowChat
       private
 
       def session_key
-        return "flow_chat:session:nil_context" unless @context
-
-        gateway = @context["request.gateway"]
-        msisdn = @context["request.msisdn"]
-
-        key = case gateway
-        when :whatsapp_cloud_api
-          "flow_chat:session:whatsapp:#{msisdn}"
-        when :nalo, :nsano
-          session_id = @context["request.id"]
-          "flow_chat:session:ussd:#{session_id}:#{msisdn}"
-        else
-          "flow_chat:session:unknown:#{msisdn}"
-        end
-
-        FlowChat.logger.debug { "CacheSessionStore: Generated session key: #{key}" }
-        key
+        "flow_chat:cached_session:#{@context["session.id"]}"
       end
 
       def session_ttl

data/lib/flow_chat/session/middleware.rb

@@ -64,32 +64,33 @@ module FlowChat
       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
+        identifier_type = @session_options.identifier || platform_default_identifier(context)
         
         case identifier_type
         when :request_id
           context["request.id"]
+        when :user_id
+          user_id = context["request.user_id"]
+          @session_options.hash_identifiers ? hash_identifier(user_id) : user_id
         when :msisdn
-          phone = context["request.msisdn"]
-          @session_options.hash_phone_numbers ? hash_phone_number(phone) : phone
+          msisdn = context["request.msisdn"]
+          @session_options.hash_identifiers ? hash_identifier(msisdn) : msisdn
         else
           raise "Invalid session identifier type: #{identifier_type}"
         end
       end
 
+      def platform_default_identifier(context)
+        platform = context["request.platform"]
+        
+        case platform
+        when :whatsapp
+          :msisdn
+        else
+          :request_id
+        end
+      end
+
       def build_session_id(flow_name, platform, gateway, identifier)
         parts = []
 
@@ -142,10 +143,10 @@ module FlowChat
         url_identifier
       end
 
-      def hash_phone_number(phone)
+      def hash_identifier(identifier)
         # Use SHA256 but only take first 8 characters for reasonable session IDs
         require 'digest'
-        Digest::SHA256.hexdigest(phone.to_s)[0, 8]
+        Digest::SHA256.hexdigest(identifier.to_s)[0, 8]
       end
     end
   end