flow_chat 0.8.2 → 0.9.0

data/lib/flow_chat/async_job.rb

@@ -0,0 +1,176 @@
+begin
+  require "active_job"
+rescue LoadError
+  # ActiveJob not available - async features will not be available
+end
+require "ostruct"
+
+module FlowChat
+  # Base class for background flow processing jobs
+  # Users inherit from this and implement execute(controller, **job_params)
+  if defined?(ActiveJob::Base)
+    class AsyncJob < ActiveJob::Base
+      queue_as :default
+
+      def perform(request_context:, **job_params)
+        FlowChat.logger.debug { "AsyncJob: Starting background job with params: #{job_params.inspect}" }
+
+        # Create BackgroundController from serialized request
+        controller = BackgroundController.new(request_context)
+
+        # User implements execute and calls processor.run themselves
+        # Pass job_params as keyword arguments to execute
+        execute(controller, **job_params)
+
+        FlowChat.logger.debug { "AsyncJob: Background job completed successfully" }
+      end
+
+      # Abstract method - user must implement
+      # User builds processor AND calls processor.run themselves
+      # Job params from use_async(JobClass, key: value) are passed as keyword arguments
+      def execute(controller, **job_params)
+        raise NotImplementedError, "Subclasses must implement #execute(controller, **job_params)"
+      end
+    end
+  else
+    # Fallback when ActiveJob is not available
+    class AsyncJob
+      def perform(request_context:, **job_params)
+        FlowChat.logger.debug { "AsyncJob: Starting background job with params: #{job_params.inspect}" }
+
+        # Create BackgroundController from serialized request
+        controller = BackgroundController.new(request_context)
+
+        # User implements execute and calls processor.run themselves
+        # Pass job_params as keyword arguments to execute
+        execute(controller, **job_params)
+
+        FlowChat.logger.debug { "AsyncJob: Background job completed successfully" }
+      end
+
+      # Abstract method - user must implement
+      # User builds processor AND calls processor.run themselves
+      # Job params from use_async(JobClass, key: value) are passed as keyword arguments
+      def execute(controller, **job_params)
+        raise NotImplementedError, "Subclasses must implement #execute(controller, **job_params)"
+      end
+
+      # Stub perform_later for testing when ActiveJob is not available
+      def self.perform_later(args)
+        new.perform(**args)
+      end
+    end
+  end
+
+  # Duck-type controller for background jobs
+  # Provides render/head no-ops and request interface
+  class BackgroundController
+    attr_reader :request, :response
+
+    def initialize(request_data)
+      FlowChat.logger.debug { "BackgroundController: Initializing with request data" }
+      @request = BackgroundRequest.new(request_data)
+      @response = nil
+    end
+
+    # Delegate params to request (mimics Rails controller behavior)
+    def params
+      request.params
+    end
+
+    def render(options)
+      FlowChat.logger.debug { "BackgroundController: render called (no-op): #{options.inspect}" }
+      @response = options
+      nil  # No-op in background
+    end
+
+    def head(status)
+      FlowChat.logger.debug { "BackgroundController: head called (no-op): #{status}" }
+      @response = {status: status}
+      nil  # No-op in background
+    end
+
+    def is_a?(klass)
+      return true if klass == FlowChat::BackgroundController
+      super
+    end
+
+    def kind_of?(klass)
+      return true if klass == FlowChat::BackgroundController
+      super
+    end
+  end
+
+  # Request object for background jobs
+  # Reconstructed from serialized webhook request data
+  class BackgroundRequest
+    attr_reader :params, :method, :headers, :host, :path, :remote_ip
+
+    def initialize(request_data)
+      @params = (request_data[:params] || {}).with_indifferent_access
+      @method = request_data[:method] || "POST"
+      @headers = OpenStruct.new(request_data[:headers] || {})
+      @host = request_data[:host]
+      @path = request_data[:path]
+      @body_content = request_data[:body]
+      @remote_ip = request_data[:remote_ip]
+
+      FlowChat.logger.debug { "BackgroundRequest: Initialized with method=#{@method}, params keys=#{@params.keys.inspect}" }
+    end
+
+    # Rails request interface compatibility
+    def request_method
+      method.upcase
+    end
+
+    def user_agent
+      @headers["User-Agent"]
+    end
+
+    def ssl?
+      # Background jobs don't have SSL context
+      false
+    end
+
+    def post?
+      method.upcase == "POST"
+    end
+
+    def get?
+      method.upcase == "GET"
+    end
+
+    def head?
+      method.upcase == "HEAD"
+    end
+
+    def body
+      # Return StringIO-like object if body content exists
+      @body_content ? BackgroundRequestBody.new(@body_content) : nil
+    end
+
+    def cookies
+      # Background jobs don't have cookies
+      {}
+    end
+  end
+
+  # Body wrapper for BackgroundRequest
+  # Provides read() method that Rails expects
+  class BackgroundRequestBody
+    def initialize(content)
+      @content = content
+      @read = false
+    end
+
+    def read
+      return "" if @read
+      @read = true
+      @content
+    end
+
+    def rewind
+      @read = false
+    end
+  end
+end

data/lib/flow_chat/config.rb

@@ -7,6 +7,8 @@ module FlowChat
     # When true (default), validation errors are combined with the original message.
     # When false, only the validation error message is shown to the user.
     mattr_accessor :combine_validation_error_with_message, default: true
+    # When true, inject logger into middleware stack. Defaults to true in Rails development.
+    mattr_accessor :inject_middleware_logger, default: defined?(Rails) && Rails.env.development?
 
     # Session configuration object
     def self.session
@@ -29,7 +31,7 @@ module FlowChat
     end
 
     class SessionConfig
-      attr_accessor :boundaries, :hash_identifiers, :identifier
+      attr_accessor :boundaries, :hash_identifiers, :identifier, :session_id_proc
 
       def initialize
         # Session boundaries control how session IDs are constructed
@@ -37,14 +39,17 @@ module FlowChat
         # :gateway = separate sessions per gateway
         # :platform = separate sessions per platform (ussd, whatsapp)
         @boundaries = [:flow, :gateway, :platform]
-        
+
         # Always hash phone numbers for privacy
         @hash_identifiers = 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
+
+        # Proc for custom session ID generation (overrides default behavior when set)
+        @session_id_proc = nil
       end
     end
 
@@ -62,35 +67,10 @@ module FlowChat
     end
 
     class WhatsappConfig
-      attr_accessor :background_job_class
-      attr_reader :message_handling_mode, :api_base_url
+      attr_reader :api_base_url
 
       def initialize
-        @message_handling_mode = :inline
-        @background_job_class = "WhatsappMessageJob"
-        @api_base_url = "https://graph.facebook.com/v22.0"
-      end
-
-      # Validate message handling mode
-      def message_handling_mode=(mode)
-        valid_modes = [:inline, :background, :simulator]
-        unless valid_modes.include?(mode.to_sym)
-          raise ArgumentError, "Invalid message handling mode: #{mode}. Valid modes: #{valid_modes.join(", ")}"
-        end
-        @message_handling_mode = mode.to_sym
-      end
-
-      # Helper methods for mode checking
-      def inline_mode?
-        @message_handling_mode == :inline
-      end
-
-      def background_mode?
-        @message_handling_mode == :background
-      end
-
-      def simulator_mode?
-        @message_handling_mode == :simulator
+        @api_base_url = "https://graph.facebook.com/v23.0"
       end
     end
 

data/lib/flow_chat/{base_executor.rb → executor.rb}

@@ -1,8 +1,8 @@
 module FlowChat
-  class BaseExecutor
+  class Executor
     def initialize(app)
       @app = app
-      FlowChat.logger.debug { "#{log_prefix}: Initialized #{platform_name} executor middleware" }
+      FlowChat.logger.debug { "#{log_prefix}: Initialized executor middleware" }
     end
 
     def call(context)
@@ -13,7 +13,7 @@ module FlowChat
       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" }
+      FlowChat.logger.debug { "#{log_prefix}: app built for flow execution" }
 
       flow = flow_class.new platform_app
       FlowChat.logger.debug { "#{log_prefix}: Flow instance created, invoking #{action} method" }
@@ -41,17 +41,12 @@ module FlowChat
 
     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"
+      "Executor"
     end
 
     def build_platform_app(context)
-      raise NotImplementedError, "Subclasses must implement build_platform_app"
+      FlowChat::App.new(context)
     end
   end
-end 
+end

data/lib/flow_chat/factory.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module FlowChat
+  # Factory provides centralized processor configuration for consistent setup across
+  # webhook and background contexts.
+  #
+  # Example:
+  #   # In config/initializers/flow_chat.rb
+  #   FlowChat::Factory.register :whatsapp do |controller|
+  #     processor = FlowChat::Processor.new(controller) do |config|
+  #       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  #       config.use_session_store FlowChat::Session::CacheSessionStore
+  #       config.use_session_config(boundaries: [:flow])
+  #       config.use_async(WhatsAppFlowJob)
+  #     end
+  #     processor.run(WhatsAppFlow, :start)
+  #   end
+  #
+  #   # In webhook controller
+  #   FlowChat::Factory.execute(:whatsapp, controller: self)
+  #
+  #   # In background job
+  #   FlowChat::Factory.execute(:whatsapp, controller: controller)
+  class Factory
+    class << self
+      # Register a processor factory with a given name
+      #
+      # @param name [Symbol] The factory name (e.g., :whatsapp, :intercom)
+      # @param block [Proc] The factory block that receives controller
+      # @return [void]
+      #
+      # @example
+      #   FlowChat::Factory.register :whatsapp do |controller|
+      #     processor = FlowChat::Processor.new(controller) do |config|
+      #       config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+      #     end
+      #     processor.run(WhatsAppFlow, :start)
+      #   end
+      def register(name, &block)
+        FlowChat.logger.debug { "Factory: Registering factory '#{name}'" }
+        factories[name] = block
+      end
+
+      # Execute a registered factory
+      #
+      # @param name [Symbol] The factory name
+      # @param controller [Object] The controller instance (webhook or background)
+      # @return [void]
+      # @raise [FactoryNotFoundError] If factory is not registered
+      #
+      # @example
+      #   FlowChat::Factory.execute(:whatsapp, controller: self)
+      def execute(name, controller:)
+        factory = factories[name]
+        raise FactoryNotFoundError, "Factory '#{name}' not registered" unless factory
+
+        FlowChat.logger.debug { "Factory: Executing factory '#{name}'" }
+        factory.call(controller)
+      end
+
+      # Check if a factory is registered
+      #
+      # @param name [Symbol] The factory name
+      # @return [Boolean]
+      def registered?(name)
+        factories.key?(name)
+      end
+
+      # Get all registered factory names
+      #
+      # @return [Array<Symbol>]
+      def registered_factories
+        factories.keys
+      end
+
+      # Clear all registered factories (primarily for testing)
+      #
+      # @return [void]
+      def clear!
+        FlowChat.logger.debug { "Factory: Clearing all registered factories" }
+        factories.clear
+      end
+
+      private
+
+      def factories
+        @factories ||= {}
+      end
+    end
+
+    # Error raised when attempting to execute an unregistered factory
+    class FactoryNotFoundError < StandardError; end
+  end
+end

data/lib/flow_chat/gateway_async_support.rb

@@ -0,0 +1,106 @@
+require_relative "async_job"
+
+module FlowChat
+  # Concern for gateways to support async background processing
+  # Mix this into gateway classes to enable async detection and job enqueueing
+  module GatewayAsyncSupport
+    attr_reader :controller, :context
+
+    # Check if gateway supports async processing
+    # Override in gateways that don't support async (e.g., USSD)
+    def async_supported?
+      true
+    end
+
+    # Detect if we're currently in background mode
+    def in_background?
+      @controller.is_a?(::FlowChat::BackgroundController)
+    end
+
+    # Check if async processing should be used
+    # Returns true if:
+    # - Not already in background mode
+    # - Processor has async enabled
+    # - Gateway supports async
+    def should_enqueue_async?
+      processor = @context["processor"]
+
+      !in_background? &&
+        processor&.async_enabled? &&
+        async_supported?
+    end
+
+    # Enqueue background job with serialized request context
+    # Returns true if job was enqueued, false otherwise
+    def enqueue_async_job
+      return false unless should_enqueue_async?
+
+      processor = @context["processor"]
+
+      FlowChat.logger.info { "#{self.class.name}: Async enabled - enqueuing background job" }
+
+      # Serialize request data for BackgroundController
+      request_data = {
+        params: @controller.request.params.to_h,
+        method: @controller.request.method,
+        headers: extract_headers_for_background(@controller.request),
+        host: extract_host(@controller.request),
+        path: extract_path(@controller.request),
+        body: extract_body_for_background(@controller.request),
+        remote_ip: extract_remote_ip(@controller.request)
+      }
+
+      # Enqueue user's job with request context and job params
+      processor.async_job_class.perform_later(
+        request_context: request_data,
+        **processor.async_job_params
+      )
+
+      FlowChat.logger.info { "#{self.class.name}: Background job enqueued successfully" }
+
+      true
+    end
+
+    # Extract serializable headers needed for background processing
+    # Override in gateways that need additional headers
+    def extract_headers_for_background(request)
+      {
+        "Content-Type" => request.headers["Content-Type"],
+        "User-Agent" => request.headers["User-Agent"]
+      }.compact
+    end
+
+    # Extract host from request for URL boundary support
+    def extract_host(request)
+      request.host
+    rescue
+      nil
+    end
+
+    # Extract path from request for URL boundary support
+    def extract_path(request)
+      request.path
+    rescue
+      nil
+    end
+
+    # Extract request body for background processing
+    # Override in gateways that need the request body
+    def extract_body_for_background(request)
+      return nil unless request.body
+
+      body_content = request.body.read
+      request.body.rewind  # Reset for subsequent reads
+      body_content
+    rescue
+      nil
+    end
+
+    # Extract remote IP from request
+    def extract_remote_ip(request)
+      request.remote_ip
+    rescue
+      nil
+    end
+  end
+end

data/lib/flow_chat/generic_async_job.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module FlowChat
+  # Generic background job that uses the Factory pattern
+  # Automatically used when use_async is called without a job class
+  #
+  # Example:
+  #   # In webhook controller
+  #   processor = FlowChat::Processor.new(self) do |config|
+  #     config.use_gateway FlowChat::Whatsapp::Gateway::CloudApi
+  #     config.use_session_store FlowChat::Session::CacheSessionStore
+  #     config.use_async(factory: :whatsapp)  # No job class - uses GenericAsyncJob
+  #   end
+  #
+  #   # Background job executes:
+  #   FlowChat::Factory.execute(:whatsapp, controller: controller)
+  class GenericAsyncJob < AsyncJob
+    def execute(controller, factory:, **job_params)
+      FlowChat.logger.debug { "GenericAsyncJob: Executing factory '#{factory}' with params: #{job_params.inspect}" }
+
+      unless FlowChat::Factory.registered?(factory)
+        raise FlowChat::Factory::FactoryNotFoundError, "Factory '#{factory}' not registered"
+      end
+
+      FlowChat::Factory.execute(factory, controller: controller)
+
+      FlowChat.logger.debug { "GenericAsyncJob: Factory '#{factory}' executed successfully" }
+    end
+  end
+end

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

@@ -1,33 +1,50 @@
 module FlowChat
   module Http
+    class ConfigurationError < StandardError; end
+
     module Gateway
       class Simple
         include FlowChat::Instrumentation
+        include FlowChat::GatewayAsyncSupport
 
         attr_reader :context
 
-        def initialize(app)
+        def initialize(app, user_params)
           @app = app
+          @user_params = user_params
+
+          validate_user_params!
         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
+          @controller = context.controller
+          params = @controller.request.params
+          request = @controller.request
+
+          # Validate request method
+          unless request.get? || request.post?
+            @controller.head :bad_request
+            return
+          end
+
+          # Set request information from user_params
+          context["request.id"] = @user_params[:session_id]
+          context["request.user_id"] = @user_params[:user_id]
+          context["request.user_name"] = @user_params[:name] if @user_params[:name]
+          context["request.msisdn"] = @user_params[:msisdn] if @user_params[:msisdn]
+          context["request.email"] = @user_params[:email] if @user_params[:email]
+          context["request.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"]
+          context["request.body"] = (params.respond_to?(:to_unsafe_h) ? params.to_unsafe_h : params.to_h).transform_keys(&:to_s)
+
+          # HTTP-specific request metadata
+          context["http.method"] = request.method
+          context["http.path"] = request.path
+          context["http.user_agent"] = request.user_agent
+          context.input = params["input"].presence || ""
 
           # Instrument message received when user provides input
           if context.input.present?
@@ -38,31 +55,62 @@ module FlowChat
             })
           end
 
-          # Process the request
-          type, prompt, choices, media = @app.call(context)
+          # Determine routing: async enqueue, background execute, or inline
+          if should_enqueue_async?
+            # HTTP request with async enabled → enqueue job and return immediately
+            enqueue_async_job
+            @controller.render json: {status: "processing"}
+          else
+            # Background OR inline → process message
+            # Process the request
+            response = @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
+            # Handle nil response (e.g., from middleware that handles the response itself)
+            unless response
+              return @controller.render json: {
+                type: :skip,
+                session_id: context["request.id"],
+                user_id: context["request.user_id"],
+                timestamp: context["request.timestamp"]
+              }
+            end
+
+            type, prompt, choices, media = response
+
+            # 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)
+            @controller.render json: response_data
+          end
         end
 
         private
 
+        def validate_user_params!
+          required_keys = [:session_id, :user_id]
+
+          required_keys.each do |key|
+            unless @user_params.key?(key)
+              raise FlowChat::Http::ConfigurationError,
+                "HTTP Simple gateway requires :#{key} in user_params"
+            end
+          end
+        end
+
         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"],
@@ -74,4 +122,4 @@ module FlowChat
       end
     end
   end
-end 
+end