flow_chat 0.8.1 → 0.9.0

data/lib/flow_chat/processor.rb

@@ -0,0 +1,188 @@
+require "middleware"
+
+module FlowChat
+  class Processor
+    include FlowChat::Instrumentation
+
+    attr_reader :custom_middleware_builder, :context, :async_job_class, :async_job_params
+
+    def initialize(controller, enable_simulator: nil)
+      FlowChat.logger.debug { "Processor: Initializing processor for controller #{controller.class.name}" }
+
+      @context = FlowChat::Context.new
+      @context["controller"] = controller
+      @context["enable_simulator"] = enable_simulator.nil? ? (defined?(Rails) && Rails.env.local?) : enable_simulator
+      @custom_middleware_builder = ::Middleware::Builder.new(name: "processor.custom_middleware_builder")
+      @session_options = FlowChat::Config.session
+      @async_job_class = nil
+      @async_job_params = {}
+
+      FlowChat.logger.debug { "Processor: Simulator mode #{@context["enable_simulator"] ? "enabled" : "disabled"}" }
+
+      yield self if block_given?
+
+      FlowChat.logger.debug { "Processor: Initialized #{self.class.name} successfully" }
+    end
+
+    def use_gateway(gateway_class, *args)
+      FlowChat.logger.debug { "Processor: Configuring gateway #{gateway_class.name} with args: #{args.inspect}" }
+      @gateway_class = gateway_class
+      @gateway_args = args
+      self
+    end
+
+    def use_session_store(session_store)
+      raise "Session store must be a class" unless session_store.is_a?(Class)
+      FlowChat.logger.debug { "Processor: Configuring session store #{session_store.name}" }
+      @context["session.store"] = session_store
+      self
+    end
+
+    def use_session_config(boundaries: nil, hash_identifiers: nil, identifier: nil, &block)
+      if block_given?
+        FlowChat.logger.debug { "Processor: Configuring session config with custom proc" }
+        @session_options = @session_options.dup
+        @session_options.session_id_proc = block
+      else
+        FlowChat.logger.debug { "Processor: 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) unless boundaries.nil?
+        @session_options.hash_identifiers = hash_identifiers unless hash_identifiers.nil?
+        @session_options.identifier = identifier unless identifier.nil?
+      end
+
+      self
+    end
+
+    def use_middleware(middleware)
+      if block_given?
+        yield custom_middleware_builder
+        return self
+      end
+
+      raise "Middleware must be a class" unless middleware.is_a?(Class)
+      FlowChat.logger.debug { "Processor: Adding custom middleware: #{middleware.name}" }
+      custom_middleware_builder.use middleware
+      self
+    end
+
+    def use_cross_platform_sessions
+      FlowChat.logger.debug { "Processor: Enabling cross-platform sessions via session configuration" }
+      use_session_config(
+        boundaries: [:flow]
+      )
+    end
+
+    def use_url_isolation
+      FlowChat.logger.debug { "Processor: 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 use_durable_sessions(cross_gateway: false)
+      FlowChat.logger.debug { "Processor: Enabling durable sessions via session configuration" }
+      use_session_config(
+        identifier: :user_id
+      )
+    end
+
+    def use_async(job_class = nil, **job_params)
+      # If no job class provided, use GenericAsyncJob with factory param
+      if job_class.nil?
+        unless job_params.key?(:factory)
+          raise ArgumentError, "When use_async is called without a job class, factory: parameter is required"
+        end
+
+        FlowChat.logger.debug { "Processor: Configuring async processing with GenericAsyncJob for factory '#{job_params[:factory]}'" }
+        @async_job_class = FlowChat::GenericAsyncJob
+      else
+        FlowChat.logger.debug { "Processor: Configuring async processing with job class #{job_class.name} and params: #{job_params.inspect}" }
+        @async_job_class = job_class
+      end
+      @async_job_params = job_params
+
+      self
+    end
+
+    def async_enabled?
+      !@async_job_class.nil?
+    end
+
+    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,
+        action: action.to_s,
+        processor_type: self.class.name
+      })
+
+      @context["processor"] = self
+      @context["flow.name"] = flow_class.name.underscore
+      @context["flow.class"] = flow_class
+      @context["flow.action"] = action
+      @context["flow.options"] = options
+
+      FlowChat.logger.debug { "Processor: Context prepared for flow #{flow_class.name}" }
+
+      stack = create_middleware_stack
+      yield stack if block_given?
+
+      FlowChat.logger.debug { "Processor: Executing middleware stack for #{flow_class.name}##{action}" }
+
+      # Instrument flow execution with timing (this will log completion via LogSubscriber)
+      instrument(Events::FLOW_EXECUTION_END, {
+        flow_name: flow_class.name.underscore,
+        action: action.to_s
+      }) do
+        stack.call(@context)
+      end
+    rescue => error
+      FlowChat.logger.error { "Processor: Flow execution failed - #{flow_class.name}##{action}, Error: #{error.class.name}: #{error.message}" }
+      FlowChat.logger.debug { "Processor: Stack trace: #{error.backtrace.join("\n")}" }
+
+      # Instrument flow execution error (this will log error via LogSubscriber)
+      instrument(Events::FLOW_EXECUTION_ERROR, {
+        flow_name: flow_class.name.underscore,
+        action: action.to_s,
+        error_class: error.class.name,
+        error_message: error.message,
+        backtrace: error.backtrace&.first(10)
+      })
+
+      raise
+    end
+
+    protected
+
+    # Helper method for building stacks
+    def create_middleware_stack
+      raise ArgumentError, "Gateway is required. Call use_gateway(gateway_class, *args) before running." unless @gateway_class
+
+      middleware_stack = ::Middleware::Builder.new(name: @gateway_class.name) do |b|
+        # Gateway always comes first
+        b.use @gateway_class, *@gateway_args
+        # Session middleware next. We need to setup our session identifiers
+        b.use FlowChat::Session::Middleware, @session_options
+
+        if @gateway_class.respond_to?(:configure_middleware_stack)
+          FlowChat.logger.debug { "Processor: Using platform specific middleware configuration" }
+          @gateway_class.configure_middleware_stack(b, custom_middleware_builder)
+        else
+          b.use custom_middleware_builder
+          FlowChat.logger.debug { "Processor: Added custom middleware" }
+        end
+
+        # Executor always goes last.
+        # Nothing can execute after it.
+        b.use FlowChat::Executor
+      end
+
+      middleware_stack.inject_logger(FlowChat.logger) if FlowChat::Config.inject_middleware_logger
+
+      middleware_stack
+    end
+  end
+end

data/lib/flow_chat/renderers/markdown_support.rb

@@ -0,0 +1,58 @@
+require "kramdown"
+require "rails-html-sanitizer"
+
+module FlowChat
+  module Renderers
+    module MarkdownSupport
+      def to_html(text)
+        return "" if text.nil?
+
+        html = Kramdown::Document.new(text.to_s, **kramdown_options).to_html.strip
+        sanitize_html(html)
+      end
+
+      def sanitize_html(html)
+        sanitized = self.class.sanitizer.sanitize(
+          html,
+          tags: allowed_tags,
+          attributes: allowed_attributes
+        )
+
+        post_process_html(sanitized)
+      end
+
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def sanitizer
+          @sanitizer ||= Rails::Html::SafeListSanitizer.new
+        end
+      end
+
+      private
+
+      # Override in subclasses to customize Kramdown options
+      # Default uses straight quotes (ASCII 39/34) instead of curly smart quotes
+      def kramdown_options
+        {smart_quotes: [39, 39, 34, 34]}
+      end
+
+      # Override in subclasses to specify allowed HTML tags
+      def allowed_tags
+        %w[b strong i em a code pre]
+      end
+
+      # Override in subclasses to specify allowed HTML attributes
+      def allowed_attributes
+        %w[href]
+      end
+
+      # Override in subclasses to post-process sanitized HTML
+      def post_process_html(html)
+        html
+      end
+    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

@@ -1,3 +1,5 @@
+require "digest"
+
 module FlowChat
   module Session
     class Middleware
@@ -52,6 +54,14 @@ module FlowChat
           return session_id
         end
 
+        # Check for custom session ID proc
+        if @session_options.session_id_proc
+          FlowChat.logger.debug { "Session::Middleware: Using custom session ID proc" }
+          session_id = @session_options.session_id_proc.call(context)
+          FlowChat.logger.debug { "Session::Middleware: Generated custom 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
@@ -64,32 +74,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 = []
 
@@ -120,19 +131,26 @@ module FlowChat
         return nil unless request
 
         # Extract host and path for URL boundary
-        host = request.host rescue nil
-        path = request.path rescue nil
+        host = begin
+          request.host
+        rescue
+          nil
+        end
+        path = begin
+          request.path
+        rescue
+          nil
+        end
 
-        # Create a normalized URL identifier: host + path 
+        # 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 != '/'
+        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._-]/, '_')
+        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]
@@ -142,10 +160,9 @@ 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

data/lib/flow_chat/simulator/controller.rb

@@ -23,12 +23,12 @@ module FlowChat
       end
 
       def default_config_key
-        "ussd"
+        :ussd
       end
 
-      def simulator_configurations
+      def configurations
         {
-          "ussd" => {
+          ussd: {
             name: "USSD (Nalo)",
             description: "USSD integration using Nalo",
             processor_type: "ussd",
@@ -41,7 +41,7 @@ module FlowChat
               session_timeout: 300
             }
           },
-          "whatsapp" => {
+          whatsapp: {
             name: "WhatsApp (Cloud API)",
             description: "WhatsApp integration using Cloud API",
             processor_type: "whatsapp",
@@ -53,6 +53,18 @@ module FlowChat
               phone_number: default_phone_number,
               contact_name: default_contact_name
             }
+          },
+          http: {
+            name: "HTTP API",
+            description: "HTTP integration with JSON request/response",
+            processor_type: "http",
+            gateway: "http_simple",
+            endpoint: "/http/webhook",
+            icon: "🌐",
+            color: "#0066cc",
+            settings: {
+              user_id: default_phone_number
+            }
           }
         }
       end
@@ -71,7 +83,7 @@ module FlowChat
           default_phone_number: default_phone_number,
           default_contact_name: default_contact_name,
           default_config_key: default_config_key,
-          configurations: simulator_configurations
+          configurations: configurations
         }
       end