flow_chat 0.9.0 → 0.10.1

data/lib/flow_chat/meta/messaging_gateway.rb

@@ -0,0 +1,471 @@
+require "json"
+
+module FlowChat
+  module Meta
+    # The Messenger Platform envelope, shared by Facebook Messenger and
+    # Instagram DMs. Both deliver entry[].messaging[] and both send through the
+    # same Send API, so the envelope is implemented once and each platform
+    # supplies only what actually differs.
+    class MessagingGateway
+      include FlowChat::Instrumentation
+      include FlowChat::GatewayAsyncSupport
+      include FlowChat::Meta::SignatureValidation
+      include FlowChat::Meta::WebhookVerification
+
+      attr_reader :context, :client
+
+      def initialize(app, config = nil)
+        @app = app
+        @config = config || configuration_class.from_credentials
+        @client = client_class.new(@config)
+
+        FlowChat.logger.info { "#{log_tag}: Initialized #{platform} gateway for account #{@config.account_id}" }
+      end
+
+      def call(context)
+        @context = context
+        @controller = context.controller
+        request = @controller.request
+
+        unless in_background?
+          if request.get? && request.params["hub.mode"] == "subscribe"
+            return handle_verification(context)
+          end
+        end
+
+        return handle_webhook(context) if request.post?
+
+        FlowChat.logger.warn { "#{log_tag}: Invalid request method or parameters - returning bad request" }
+        @controller.head :bad_request
+      end
+
+      def self.configure_middleware_stack(builder, custom_middleware)
+        builder.use custom_middleware
+        builder.use choice_mapper_class
+      end
+
+      # --- Hooks each platform overrides ---
+
+      def gateway_name
+        raise NotImplementedError
+      end
+
+      def configuration_class
+        raise NotImplementedError
+      end
+
+      def client_class
+        raise NotImplementedError
+      end
+
+      def renderer_class
+        raise NotImplementedError
+      end
+
+      # Meta names the subscription this delivery came from. Messenger uses
+      # "page". Instagram's value depends on how the app is set up, so each
+      # platform states its own rather than sharing a guess.
+      def expected_webhook_object
+        "page"
+      end
+
+      private
+
+      def handle_webhook(context)
+        begin
+          parse_request_body(@controller.request)
+        rescue JSON::ParserError => e
+          FlowChat.logger.error { "#{log_tag}: Failed to parse webhook body: #{e.message}" }
+          return @controller.head :bad_request
+        end
+
+        is_simulator_mode = simulate?(context)
+        context["simulator_mode"] = true if is_simulator_mode
+
+        unless in_background? || is_simulator_mode || valid_webhook_signature?(@controller.request)
+          FlowChat.logger.warn { "#{log_tag}: Invalid webhook signature - dropping request" }
+          return @controller.head :ok
+        end
+
+        # Warn rather than debug. A gateway whose expected_webhook_object does not
+        # match what the app is actually subscribed to drops every delivery here
+        # and answers 200, so the symptom is a bot that receives nothing while the
+        # dashboard reports successful deliveries. That is worth a line in
+        # production logs, not one only visible at debug level.
+        if @body["object"].present? && @body["object"] != expected_webhook_object
+          FlowChat.logger.warn {
+            "#{log_tag}: Ignoring webhook for object '#{@body["object"]}', expected " \
+            "'#{expected_webhook_object}'. If every delivery lands here, this gateway's " \
+            "expected_webhook_object does not match the app's webhook subscription."
+          }
+          return @controller.head :ok
+        end
+
+        entries = @body["entry"]
+        unless entries.is_a?(Array) && entries.any?
+          return @controller.head :ok
+        end
+
+        # Only one event per delivery can drive a flow, because only one can own
+        # the response to this request.
+        flow_ran = false
+
+        entries.each do |entry|
+          # Published by whichever pass is first to see this delivery, and
+          # only once.
+          #
+          # With async enabled the gem publishes here, enqueues, and the job
+          # re-enters this method on the same body, so publishing in both
+          # announced every receipt, echo and standby event twice. The job the
+          # gem enqueues therefore carries word that they are already out, and
+          # skips them. The request is the better publisher of the two: it
+          # already holds the delivery, so a receipt is announced when it
+          # arrives rather than whenever the queue gets to it, and survives a
+          # job that is never picked up.
+          #
+          # A background pass with nothing behind it publishes. An application
+          # is free to build its own request context and enqueue a job itself,
+          # which is what fanning one shared webhook out to several accounts
+          # takes, and no foreground pass ever runs for those.
+          publish_side_events(entry) unless side_events_already_published?
+
+          events = entry["messaging"]
+          next unless events.is_a?(Array)
+
+          events.each do |event|
+            # Only a message or a postback drives a flow, which also rules out
+            # a receipt: it carries neither. An echo is the one thing that has
+            # to be named, because it does carry a message and would otherwise
+            # run a flow against our own outbound reply.
+            next unless drives_flow?(event)
+            next if echo?(event)
+
+            if flow_ran
+              FlowChat.logger.warn { "#{log_tag}: A second message arrived in the same delivery and was not processed" }
+              next
+            end
+            flow_ran = true
+
+            case handle_message(context, entry, event)
+            when :rejected then return @controller.head :forbidden
+            when :enqueued then return @controller.head :ok
+            when :rendered then return nil
+            end
+          end
+        end
+
+        @controller.head :ok
+      end
+
+      # Everything in a delivery that is not the one event driving a flow.
+      #
+      # Standby carries the same events for a thread another app owns, which is
+      # what a secondary receiver sees under the handover protocol. It is
+      # published whole and never run: a flow answering here would be talking
+      # over whoever Meta handed the thread to, and the send would be refused in
+      # any case. Whether to record it, and what to do about it, is the
+      # application's to decide.
+      #
+      # Nothing has to be subscribed for standby to arrive. A delivery switches
+      # to it the moment a business names another app the primary receiver, on
+      # the same subscription that was already in place.
+      def publish_side_events(entry)
+        Array(entry["standby"]).each do |event|
+          publish_standby(entry, event) if event.is_a?(Hash)
+        end
+
+        events = entry["messaging"]
+        return unless events.is_a?(Array)
+
+        # Receipts first, as they always were: a receipt arriving ahead of a
+        # message in the same batch must not be read as the message.
+        events.each { |event| handle_status(entry, event) if status_event?(event) }
+
+        events.each do |event|
+          next if status_event?(event)
+
+          if echo?(event)
+            publish_echo(entry, event)
+          elsif !drives_flow?(event)
+            publish_unmodelled(entry, event)
+          end
+        end
+      end
+
+      def status_event?(event)
+        event.key?("delivery") || event.key?("read")
+      end
+
+      def echo?(event)
+        event.dig("message", "is_echo") == true
+      end
+
+      def drives_flow?(event)
+        event.key?("message") || event.key?("postback")
+      end
+
+      def handle_message(context, entry, event)
+        account_id = entry["id"]
+
+        # Skipped in simulator mode rather than requiring the simulator to
+        # send an id that matches a real configuration: the simulator's
+        # whole point is running a turn with no live credentials at hand.
+        # Safe to skip, not a hole for real traffic, because
+        # context["simulator_mode"] is only ever true once simulate? has
+        # already checked the signed simulator cookie, above in
+        # handle_webhook.
+        expected = @config.webhook_account_id
+        ours = expected.present? && account_id.to_s == expected.to_s
+
+        unless context["simulator_mode"] || ours
+          FlowChat.logger.warn { "#{log_tag}: Webhook for account '#{account_id}' but configured for #{expected.inspect} - rejecting" }
+          return :rejected
+        end
+
+        sender_id = event.dig("sender", "id")
+        message = event["message"] || event["postback"]
+
+        context["request.id"] = sender_id
+        context["request.user_id"] = sender_id
+        context["request.msisdn"] = nil
+        context["request.message_id"] = message["mid"]
+        context["request.gateway"] = gateway_name
+        context["request.platform"] = platform
+        context["request.timestamp"] = Time.current.iso8601
+        context["request.body"] = @body
+
+        context["#{platform}.account.id"] = account_id
+        context["#{platform}.client"] = @client
+
+        extract_message_content!(event, context)
+
+        instrument(FlowChat::Instrumentation::Events::MESSAGE_RECEIVED, {
+          from: sender_id,
+          message: context.input,
+          message_type: event.key?("postback") ? "postback" : "message",
+          message_id: message["mid"]
+        })
+
+        if should_enqueue_async?
+          enqueue_async_job
+          return :enqueued
+        end
+
+        if context["simulator_mode"]
+          handle_message_simulator(context)
+          :rendered
+        else
+          handle_message_inline(context)
+          :processed
+        end
+      end
+
+      # A postback's payload, a quick reply's payload, and otherwise the text.
+      # An attachment-only turn has blank input, matching the media contract the
+      # other gateways follow.
+      def extract_message_content!(event, context)
+        if event.key?("postback")
+          context.input = event.dig("postback", "payload").to_s
+          return
+        end
+
+        message = event["message"]
+
+        if message["quick_reply"]
+          context.input = message.dig("quick_reply", "payload").to_s
+          return
+        end
+
+        attachments = message["attachments"]
+        if attachments.is_a?(Array) && attachments.any?
+          attachment = attachments.first
+
+          # Meta delivers a shared location as an attachment like any image, but
+          # every other gateway here puts one on request.location, and a flow
+          # reading app.location should not have to know which platform it is on.
+          if attachment["type"].to_s == "location"
+            coordinates = attachment.dig("payload", "coordinates") || {}
+            context["request.location"] = {
+              latitude: coordinates["lat"],
+              longitude: coordinates["long"],
+              name: attachment["title"]
+            }.compact
+          else
+            context["request.media"] = {
+              type: normalize_attachment_type(attachment["type"]),
+              url: attachment.dig("payload", "url")
+            }
+          end
+        end
+
+        context.input = message["text"].presence || ""
+      end
+
+      # "file" is Meta's name for what every other gateway here calls a document.
+      def normalize_attachment_type(type)
+        case type.to_s
+        when "file" then :document
+        when "" then nil
+        else type.to_s.to_sym
+        end
+      end
+
+      def handle_status(entry, event)
+        %w[delivery read].each do |kind|
+          payload = event[kind]
+          next unless payload
+
+          instrument(FlowChat::Instrumentation::Events::MESSAGE_STATUS, {
+            platform: platform,
+            gateway: gateway_name,
+            account_id: entry["id"],
+            recipient: event.dig("sender", "id"),
+            status: kind,
+            timestamp: event["timestamp"],
+            value: payload
+          })
+        end
+      end
+
+      # An echo reports a message sent on this thread by someone other than the
+      # user. Which someone decides what the application does about it: a human
+      # replying from the page inbox usually means the flow should stand down.
+      def publish_echo(entry, event)
+        instrument(FlowChat::Instrumentation::Events::WEBHOOK_RECEIVED, {
+          platform: platform,
+          gateway: gateway_name,
+          field: "message_echoes",
+          account_id: entry["id"],
+          echo_origin: echo_origin(event),
+          value: event
+        })
+      end
+
+      # Named for the channel rather than the event, because that is the part
+      # the application cannot work out for itself: a standby message looks
+      # exactly like an owned one, and only where it arrived says otherwise.
+      def publish_standby(entry, event)
+        FlowChat.logger.info { "#{log_tag}: Publishing standby event for account #{entry["id"]}" }
+
+        instrument(FlowChat::Instrumentation::Events::WEBHOOK_RECEIVED, {
+          platform: platform,
+          gateway: gateway_name,
+          field: "standby",
+          account_id: entry["id"],
+          value: event
+        })
+      end
+
+      def echo_origin(event)
+        app_id = event.dig("message", "app_id")
+
+        return :human_agent if app_id.blank?
+        return :self if app_id.to_s == @config.app_id.to_s
+
+        :other_app
+      end
+
+      # Everything that is not a message, its receipt, or an echo. Reactions,
+      # referrals, opt-ins, handovers, policy enforcement: all of it is the
+      # application's domain, so it is published whole rather than interpreted.
+      def publish_unmodelled(entry, event)
+        field = (event.keys - %w[sender recipient timestamp]).first
+
+        FlowChat.logger.info { "#{log_tag}: Publishing webhook event '#{field}'" }
+
+        instrument(FlowChat::Instrumentation::Events::WEBHOOK_RECEIVED, {
+          platform: platform,
+          gateway: gateway_name,
+          field: field,
+          account_id: entry["id"],
+          value: event
+        })
+      end
+
+      def handle_message_inline(context)
+        response = @app.call(context)
+        return unless response
+
+        type, prompt, choices, media = response
+
+        result = report_delivery_failure(
+          context,
+          to: context["request.user_id"],
+          session_id: context["request.id"],
+          message: prompt,
+          message_type: (type == :prompt) ? "prompt" : "terminal",
+          gateway: gateway_name,
+          platform: platform
+        ) do
+          @client.send_message(context["request.user_id"], prompt, choices: choices, media: media)
+        end
+
+        context["#{platform}.message_result"] = result
+
+        # report_delivery_failure already reported this; a nil result here
+        # means the platform did not accept the message, and instrumenting
+        # MESSAGE_SENT anyway counted a delivery that never happened.
+        return unless result
+
+        instrument(FlowChat::Instrumentation::Events::MESSAGE_SENT, {
+          to: context["request.user_id"],
+          session_id: context["request.id"],
+          message: prompt,
+          message_type: (type == :prompt) ? "prompt" : "terminal",
+          gateway: gateway_name,
+          platform: platform,
+          content_length: prompt.to_s.length,
+          platform_message_id: platform_message_id_from(result),
+          duration_ms: context[FlowChat::Instrumentation::DELIVERY_DURATION_KEY],
+          timestamp: context["request.timestamp"]
+        })
+      end
+
+      # The Send API answers with the id it assigned, flatter than WhatsApp's
+      # messages[0].id.
+      def platform_message_id_from(result)
+        return nil unless result.is_a?(Hash)
+
+        result["message_id"]
+      end
+
+      def handle_message_simulator(context)
+        response = @app.call(context)
+        return unless response
+
+        _, prompt, choices, media = response
+        rendered = renderer_class.new(prompt, choices: choices, media: media).render
+
+        @controller.render json: {
+          mode: "simulator",
+          webhook_processed: true,
+          would_send: rendered,
+          message_info: {
+            to: context["request.user_id"],
+            timestamp: Time.now.iso8601
+          }
+        }
+
+        nil
+      end
+
+      def simulate?(context)
+        return false unless context["enable_simulator"]
+
+        @body.dig("simulator_mode") &&
+          FlowChat::Security.valid_simulator_cookie?(@controller.request.cookies[FlowChat::Security::SIMULATOR_COOKIE_NAME])
+      end
+
+      def parse_request_body(request)
+        return @body if @body
+
+        @body = if request.body.nil?
+          {}
+        else
+          request.body.rewind if request.body.respond_to?(:rewind)
+          JSON.parse(request.body.read)
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/meta/signature.rb

@@ -0,0 +1,30 @@
+require "openssl"
+
+module FlowChat
+  module Meta
+    # Whether a body carries Meta's signature for a given secret.
+    #
+    # The decision on its own, with no configuration, logging or gateway around
+    # it. Meta signs every product's webhook the same way, and an application
+    # that receives one outside a gateway needs this answer without the rest:
+    # a single endpoint serving several tenants has to verify the delivery
+    # before it can know whose it is, which is before it has a gateway to ask.
+    #
+    # SignatureValidation is the gateway's way in, and calls this.
+    module Signature
+      HEADER = "X-Hub-Signature-256"
+
+      # Total, rather than raising on a missing secret. A caller with no secret
+      # configured is not asking a different question; it is asking this one and
+      # the answer is no. A gateway that would rather treat that as the
+      # developer's mistake checks for it before asking.
+      def self.valid?(body, header, secret)
+        return false if secret.to_s.strip.empty? || header.to_s.empty?
+
+        expected = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), secret, body.to_s)
+
+        FlowChat::Security.secure_compare(header.to_s.delete_prefix("sha256="), expected)
+      end
+    end
+  end
+end

data/lib/flow_chat/meta/signature_validation.rb

@@ -0,0 +1,66 @@
+require "openssl"
+
+module FlowChat
+  module Meta
+    # X-Hub-Signature-256 validation, shared by every Meta webhook gateway.
+    #
+    # The including gateway must have @config responding to #app_secret and
+    # #skip_signature_validation, and must include FlowChat::Meta::GatewayIdentity
+    # (directly or via another Meta:: behavior module) to supply platform_label
+    # and configuration_error_class.
+    #
+    # What it adds over FlowChat::Meta::Signature is the gateway's share: the
+    # opt out, treating a missing secret as the developer's mistake rather than
+    # an answer, reading the body off a Rack request, and the logging. An
+    # application holding Meta's webhooks outside a gateway wants Signature.
+    module SignatureValidation
+      include FlowChat::Meta::GatewayIdentity
+
+      private
+
+      def valid_webhook_signature?(request)
+        if @config.skip_signature_validation
+          FlowChat.logger.debug { "#{log_tag}: Webhook signature validation is disabled" }
+          return true
+        end
+
+        # Deliberately wider than a nil-or-empty check: a whitespace-only secret is
+        # never intentional, and computing an HMAC with it would silently accept
+        # traffic under a "secret" that offers no protection.
+        if @config.app_secret.blank?
+          error_msg = "#{platform_label} app_secret is required for webhook signature validation. " \
+            "Either configure app_secret or set skip_signature_validation=true to explicitly disable validation."
+          FlowChat.logger.error { "#{log_tag}: #{error_msg}" }
+          raise configuration_error_class, error_msg
+        end
+
+        signature_header = request.headers[FlowChat::Meta::Signature::HEADER]
+        unless signature_header
+          FlowChat.logger.warn { "#{log_tag}: No #{FlowChat::Meta::Signature::HEADER} header found in request" }
+          return false
+        end
+
+        request.body.rewind
+        body = request.body.read
+        request.body.rewind
+
+        signature_valid = FlowChat::Meta::Signature.valid?(body, signature_header, @config.app_secret)
+
+        if signature_valid
+          FlowChat.logger.debug { "#{log_tag}: Webhook signature validation successful" }
+        else
+          FlowChat.logger.warn { "#{log_tag}: Webhook signature validation failed - signatures do not match" }
+        end
+
+        signature_valid
+      rescue => e
+        # A misconfiguration is the developer's problem and must not be swallowed
+        # into a plain "invalid signature".
+        raise if e.is_a?(configuration_error_class)
+
+        FlowChat.logger.error { "#{log_tag}: Error validating webhook signature: #{e.class.name}: #{e.message}" }
+        false
+      end
+    end
+  end
+end

data/lib/flow_chat/meta/webhook_verification.rb

@@ -0,0 +1,43 @@
+module FlowChat
+  module Meta
+    # The GET handshake Meta performs when a webhook URL is registered.
+    #
+    # The including gateway must have @config responding to #verify_token,
+    # @controller, and must include FlowChat::Meta::GatewayIdentity (directly or
+    # via another Meta:: behavior module) to supply #platform.
+    #
+    # What it adds over FlowChat::Meta::Challenge is the gateway's share:
+    # instrumenting the outcome and answering through the controller. An
+    # application holding Meta's webhooks outside a gateway wants Challenge.
+    module WebhookVerification
+      include FlowChat::Meta::GatewayIdentity
+
+      private
+
+      def handle_verification(context)
+        params = @controller.request.params
+
+        challenge = FlowChat::Meta::Challenge.answer(params, @config.verify_token)
+        verified = !challenge.nil?
+
+        FlowChat.logger.debug { "#{log_tag}: Webhook verification - provided token matches: #{verified}" }
+
+        if verified
+          instrument(FlowChat::Instrumentation::Events::WEBHOOK_VERIFIED, {
+            challenge: challenge,
+            platform: platform
+          })
+
+          @controller.render plain: challenge
+        else
+          instrument(FlowChat::Instrumentation::Events::WEBHOOK_FAILED, {
+            reason: "Invalid verify token",
+            platform: platform
+          })
+
+          @controller.head :forbidden
+        end
+      end
+    end
+  end
+end

data/lib/flow_chat/named_configuration.rb

@@ -0,0 +1,65 @@
+module FlowChat
+  # The named-configuration registry every platform's Configuration shares.
+  #
+  # Storage is a class-level ivar on the including class, not a class variable.
+  # A @@configurations in a shared module would give every platform one merged
+  # registry, so a name registered for Messenger would resolve for WhatsApp.
+  module NamedConfiguration
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def register(name, config)
+        FlowChat.logger.debug { "#{self.name}: Registering configuration '#{name}'" }
+        configurations[name.to_sym] = config
+      end
+
+      def get(name)
+        config = configurations[name.to_sym]
+        unless config
+          FlowChat.logger.error { "#{self.name}: Configuration '#{name}' not found" }
+          raise ArgumentError, "#{configuration_label} configuration '#{name}' not found"
+        end
+
+        FlowChat.logger.debug { "#{self.name}: Retrieved configuration '#{name}'" }
+        config
+      end
+
+      def exists?(name)
+        configurations.key?(name.to_sym)
+      end
+
+      def configuration_names
+        configurations.keys
+      end
+
+      def clear_all!
+        FlowChat.logger.debug { "#{name}: Clearing all registered configurations" }
+        configurations.clear
+      end
+
+      # The platform's name as it appears in the not-found message. Overridden
+      # where the constant name and the product name differ, as with WhatsApp.
+      def configuration_label
+        name.split("::")[-2]
+      end
+
+      private
+
+      # The registry itself is not API. It replaced a @@configurations class
+      # variable, which was equally internal, and configuration_names is the
+      # public way to ask what is registered.
+      def configurations
+        @configurations ||= {}
+      end
+    end
+
+    def register_as(name)
+      FlowChat.logger.debug { "#{self.class.name}: Registering configuration as '#{name}'" }
+      @name = name.to_sym
+      self.class.register(@name, self)
+      self
+    end
+  end
+end