flow_chat 0.8.2 → 0.10.0

data/lib/flow_chat/phone_number_util.rb

@@ -1,47 +1,49 @@
 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)
+    class << self
+      def to_e164(phone_number)
+        return "" 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
-    end
 
-    private
+      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
+      def require_phonelib_safely
+        return if defined?(Phonelib)
+
+        # Temporarily stub Rails if it doesn't exist
+        if defined?(Rails)
+          require "phonelib"
+        else
+          stub_rails = Module.new do
+            def 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)
         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}"
+      def 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
-end 
+end

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

@@ -3,13 +3,15 @@ module FlowChat
     attr_reader :user_input
 
     def initialize(input)
-      @user_input = input
+      # Always work with a FlowChat::Input so `submitted?` (text OR attachment)
+      # gates the turn, and validate/transform receive the rich turn. A bare
+      # string (or nil) is wrapped as text.
+      @user_input = input.is_a?(FlowChat::Input) ? input : FlowChat::Input.new(text: input)
     end
 
     def ask(msg, choices: nil, transform: nil, validate: nil, media: nil)
-      if user_input.present?
-        input = user_input
-        validation_error = validate.call(input) if validate.present?
+      if user_input.submitted?
+        validation_error = validate.call(user_input) if validate.present?
 
         if validation_error.present?
           # Use config to determine whether to combine validation error with original message
@@ -21,8 +23,7 @@ module FlowChat
           prompt!(message, choices: choices, media: media)
         end
 
-        input = transform.call(input) if transform.present?
-        return input
+        return transform.present? ? transform.call(user_input) : user_input.to_s
       end
 
       # Pass raw message and media separately to the renderer
@@ -56,14 +57,6 @@ module FlowChat
 
     private
 
-    def validate_media_choices_compatibility(media, choices)
-      return unless media && choices
-
-      if choices.length > 3
-        raise ArgumentError, "Media with more than 3 choices is not supported. Please use either media OR choices for more than 3 options."
-      end
-    end
-
     def normalize_choices(choices)
       case choices
       when nil
@@ -78,8 +71,12 @@ module FlowChat
     end
 
     def prompt!(msg, choices: nil, media: nil)
-      validate_media_choices_compatibility(media, choices)
-
+      # Media plus any number of choices is a supported combination: every
+      # renderer either carries the media as its own message ahead of the
+      # choice surface, or (WhatsApp, <=3 choices) as a header on the same
+      # message. There is no platform-level reason to cap the choice count
+      # here - that decision, if one is ever needed, belongs to a specific
+      # renderer, not to this shared entry point.
       choices = normalize_choices(choices)
       raise FlowChat::Interrupt::Prompt.new(msg, choices: choices, media: media)
     end

data/lib/flow_chat/renderers/markdown_support.rb

@@ -0,0 +1,167 @@
+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
+
+      # Markdown rendered as plain text, for platforms with no rich text at all.
+      # Messenger and Instagram both fall here: they display exactly the
+      # characters sent, so any leftover markup is noise the user reads.
+      def to_plain_text(text)
+        return "" if text.nil?
+
+        html = Kramdown::Document.new(text.to_s, **kramdown_options).to_html.strip
+        html_to_plain_text(html)
+      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
+
+      # A list whose items hold no further list, which is the only kind that
+      # can be turned into text without looking inside itself first.
+      INNERMOST_UNORDERED = %r{<ul[^>]*>((?:(?!<[uo]l\b).)*?)</ul>}m
+      INNERMOST_ORDERED = %r{<ol[^>]*>((?:(?!<[uo]l\b).)*?)</ol>}m
+
+      # Renders lists from the inside out.
+      #
+      # A single non-greedy pass over <ul>(.*?)</ul> pairs an outer opening tag
+      # with the *inner* list's closing tag, so on a nested list only the first
+      # item kept its bullet and the leftover </li></ul> was later stripped as
+      # a bare tag - leaving stray indented lines, and on some inputs raw
+      # markup, in a message a user reads.
+      #
+      # Innermost lists are replaced first and the loop repeats, so by the time
+      # an outer list is matched its children are already plain text and it
+      # contains no list markup to mispair with. Continuation lines are
+      # indented, which is what makes the nesting legible once the tags are
+      # gone.
+      def replace_lists(html)
+        # The markdown's own indentation survives into the HTML as whitespace
+        # around the list tags. Removed once, up front, so that from here on the
+        # only indentation in play is the kind this method adds - otherwise the
+        # two compound and each level steps further right than the last.
+        result = html.gsub(%r{\s*(</?(?:ul|ol|li)\b[^>]*>)\s*}m) { $1 }
+
+        loop do
+          changed = false
+
+          # Each rendered list opens on its own line. Without it, a nested list
+          # would run straight on from the text of the item holding it, and the
+          # parent pass would see one line where there are two.
+          result = result.gsub(INNERMOST_UNORDERED) do
+            changed = true
+            "\n" + list_items($1) { |item, _index| "• #{item}" }
+          end
+
+          result = result.gsub(INNERMOST_ORDERED) do
+            changed = true
+            "\n" + list_items($1) { |item, index| "#{index}. #{item}" }
+          end
+
+          break unless changed
+        end
+
+        result
+      end
+
+      def list_items(html)
+        html.scan(%r{<li[^>]*>(.*?)</li>}m).flatten.map.with_index(1) do |item, index|
+          # Continuation lines are left exactly as they are: they were produced
+          # by an earlier pass over a nested list and already carry that level's
+          # indentation, which stripping would flatten. Source whitespace is
+          # gone by now - replace_lists removes it around the list tags before
+          # any of this runs.
+          lines = item.strip.split("\n").reject { |line| line.strip.empty? }
+          marked = yield(lines.shift.to_s.strip, index)
+
+          # Anything after the first line is an already-rendered nested list.
+          [marked, *lines.map { |line| "  #{line}" }].join("\n")
+        end.join("\n")
+      end
+
+      def html_to_plain_text(html)
+        result = html.dup
+
+        # Code blocks and inline code keep their content, lose their markers.
+        result.gsub!(%r{<pre[^>]*><code[^>]*>(.*?)</code></pre>}m) { $1.strip }
+        result.gsub!(%r{<code[^>]*>(.*?)</code>}m) { $1 }
+
+        # Links first: the anchor text is needed before tags are stripped.
+        result.gsub!(%r{<a[^>]*href=["']([^"']+)["'][^>]*>(.*?)</a>}m) do
+          url, text = $1, $2
+          (text == url) ? url : "#{text} (#{url})"
+        end
+
+        result = replace_lists(result)
+
+        result.gsub!(%r{<blockquote[^>]*>(.*?)</blockquote>}m) do
+          $1.lines.map { |line| "> #{line.strip}" }.join("\n")
+        end
+
+        result.gsub!(%r{<p[^>]*>(.*?)</p>}m) { "#{$1}\n\n" }
+        result.gsub!(/<br\s*\/?>/, "\n")
+
+        # Every remaining tag, emphasis included, goes without replacement.
+        result.gsub!(/<[^>]+>/, "")
+
+        result.gsub!("&amp;", "&")
+        result.gsub!("&lt;", "<")
+        result.gsub!("&gt;", ">")
+        result.gsub!("&quot;", '"')
+        result.gsub!("&#39;", "'")
+        result.gsub!("&nbsp;", " ")
+
+        result.gsub!(/\n{3,}/, "\n\n")
+
+        result.strip
+      end
+    end
+  end
+end

data/lib/flow_chat/security.rb

@@ -0,0 +1,76 @@
+require "openssl"
+
+begin
+  require "active_support/security_utils"
+rescue LoadError
+  # Older Active Support, or an install without it. secure_compare falls back
+  # to its own implementation below.
+end
+
+module FlowChat
+  # Shared security helpers: constant-time comparison for webhook secrets and
+  # signatures, and the signed cookie that authorizes simulator mode.
+  module Security
+    SIMULATOR_COOKIE_NAME = "flowchat_simulator"
+
+    # How long a simulator cookie stays valid.
+    SIMULATOR_COOKIE_TTL = 24 * 60 * 60
+
+    class << self
+      # Compare two strings without leaking their contents through timing.
+      def secure_compare(a, b)
+        a = a.to_s
+        b = b.to_s
+
+        if defined?(ActiveSupport::SecurityUtils)
+          ActiveSupport::SecurityUtils.secure_compare(a, b)
+        else
+          fallback_secure_compare(a, b)
+        end
+      end
+
+      # The value to store in the simulator cookie: "timestamp:signature".
+      def simulator_cookie(timestamp = Time.now.to_i)
+        "#{timestamp}:#{simulator_signature(timestamp)}"
+      end
+
+      # A simulator cookie is valid when it carries a recent timestamp signed
+      # with the configured simulator secret.
+      def valid_simulator_cookie?(cookie)
+        return false if FlowChat::Config.simulator_secret.blank? || cookie.blank?
+
+        timestamp_str, signature = cookie.to_s.split(":", 2)
+        return false unless timestamp_str && signature
+
+        timestamp = timestamp_str.to_i
+        return false if timestamp <= 0
+        return false if (Time.now.to_i - timestamp).abs > SIMULATOR_COOKIE_TTL
+
+        secure_compare(signature, simulator_signature(timestamp_str))
+      end
+
+      def simulator_signature(timestamp)
+        OpenSSL::HMAC.hexdigest(
+          OpenSSL::Digest.new("sha256"),
+          FlowChat::Config.simulator_secret,
+          "simulator:#{timestamp}"
+        )
+      end
+
+      private
+
+      # What Active Support does, for installs that do not have it: compare
+      # digests rather than the inputs, so the comparison runs over a fixed
+      # length and times neither the contents nor the length of a secret. The
+      # equality check afterwards is what makes a digest collision harmless.
+      def fallback_secure_compare(a, b)
+        digest_a = OpenSSL::Digest.digest("SHA256", a)
+        digest_b = OpenSSL::Digest.digest("SHA256", b)
+
+        result = 0
+        digest_a.bytes.zip(digest_b.bytes) { |byte_a, byte_b| result |= byte_a ^ byte_b }
+        result == 0 && a == b
+      end
+    end
+  end
+end

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
@@ -65,7 +75,7 @@ module FlowChat
 
       def get_session_identifier(context)
         identifier_type = @session_options.identifier || platform_default_identifier(context)
-        
+
         case identifier_type
         when :request_id
           context["request.id"]
@@ -82,10 +92,14 @@ module FlowChat
 
       def platform_default_identifier(context)
         platform = context["request.platform"]
-        
+
         case platform
         when :whatsapp
           :msisdn
+        when :messenger, :instagram
+          # Neither platform exposes a phone number. The sender id is scoped to
+          # the app and the account, and is stable per user.
+          :user_id
         else
           :request_id
         end
@@ -121,19 +135,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]
@@ -144,9 +165,13 @@ module FlowChat
       end
 
       def hash_identifier(identifier)
-        # Use SHA256 but only take first 8 characters for reasonable session IDs
-        require 'digest'
-        Digest::SHA256.hexdigest(identifier.to_s)[0, 8]
+        # First 32 hex chars of SHA256 = 128 bits. The old 8-char (32-bit)
+        # truncation was far too short: distinct users started colliding
+        # (birthday bound) around ~77k identifiers, and a collision means two
+        # users share a session. 128 bits pushes that boundary past ~2^64
+        # identifiers (collision-safe in practice) at half the length of the
+        # full 64-char digest.
+        Digest::SHA256.hexdigest(identifier.to_s)[0, 32]
       end
     end
   end