LeadMagnet/leadchat
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

refactor: strategy pattern for mailbox conversation finding (#12766)

Browse Source 
Co-authored-by: Pranav <pranav@chatwoot.com>
Co-authored-by: Muhsin Keloth <muhsinkeramam@gmail.com>
This commit is contained in:
Shivam Mishra
2025-11-10 20:47:18 +05:30
committed by GitHub
parent fb1aa085cf
commit 615e81731c
19 changed files with 1527 additions and 553 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
app/mailboxes/application_mailbox.rb
View File

@@ -4,38 +4,21 @@ class ApplicationMailbox < ActionMailbox::Base
# Last part is the regex for the UUID
# Eg: email should be something like : reply+6bdc3f4d-0bec-4515-a284-5d916fdde489@domain.com
REPLY_EMAIL_UUID_PATTERN = /^reply\+([0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12})$/i
CONVERSATION_MESSAGE_ID_PATTERN = %r{conversation/([a-zA-Z0-9-]*?)/messages/(\d+?)@(\w+\.\w+)}
# routes as a reply to existing conversations
# Route all emails to verified channels to the unified reply mailbox
# The ConversationFinder will determine if it's a reply or new conversation
routing(
->(inbound_mail) { valid_to_address?(inbound_mail) && (reply_uuid_mail?(inbound_mail) || in_reply_to_mail?(inbound_mail)) } => :reply
)
# routes as a new conversation in email channel
routing(
->(inbound_mail) { valid_to_address?(inbound_mail) && EmailChannelFinder.new(inbound_mail.mail).perform.present? } => :support
lambda { |inbound_mail|
valid_to_address?(inbound_mail) &&
(reply_uuid_mail?(inbound_mail) || EmailChannelFinder.new(inbound_mail.mail).perform.present?)
} => :reply
)
# catchall
routing(all: :default)
class << self
# checks if follow this pattern then send it to reply_mailbox
# <account/#{@account.id}/conversation/#{@conversation.uuid}@#{@account.inbound_email_domain}>
def in_reply_to_mail?(inbound_mail)
in_reply_to = inbound_mail.mail.in_reply_to
in_reply_to.present? && (
in_reply_to_matches?(in_reply_to) || Message.exists?(source_id: in_reply_to)
)
end
def in_reply_to_matches?(in_reply_to)
Array.wrap(in_reply_to).any? { it.match?(CONVERSATION_MESSAGE_ID_PATTERN) }
end
# checks if follow this pattern send it to reply_mailbox
# reply+<conversation-uuid>@<mailer-domain.com>
# checks if follows this pattern: reply+<conversation-uuid>@<mailer-domain.com>
def reply_uuid_mail?(inbound_mail)
inbound_mail.mail.to&.any? do |email|
conversation_uuid = email.split('@')[0]

23
app/mailboxes/imap/imap_mailbox.rb
View File

@@ -3,6 +3,8 @@ class Imap::ImapMailbox
include IncomingEmailValidityHelper
attr_accessor :channel, :account, :inbox, :conversation, :processed_mail
FALLBACK_CONVERSATION_PATTERN = %r{account/(\d+)/conversation/([a-zA-Z0-9-]+)@}
def process(mail, channel)
@inbound_mail = mail
@channel = channel
@@ -49,19 +51,32 @@ class Imap::ImapMailbox
end
def find_conversation_by_reference_ids
return if @inbound_mail.references.blank? && in_reply_to.present?
return if @inbound_mail.references.blank?
message = find_message_by_references
if message.present?
conversation = @inbox.conversations.find_by(id: message.conversation_id)
return conversation if conversation.present?
end
return if message.nil?
@inbox.conversations.find(message.conversation_id)
# FALLBACK_PATTERN use to find a conversation that is started by an agent (no incoming message yet)
conversation_id = find_conversation_by_references
@inbox.conversations.find_by(uuid: conversation_id) if conversation_id.present?
end
def in_reply_to
@processed_mail.in_reply_to
end
def find_conversation_by_references
references = Array.wrap(@inbound_mail.references)
references.each do |message_id|
match = FALLBACK_CONVERSATION_PATTERN.match(message_id)
return match[2] if match.present?
end
end
def find_message_by_references
message_to_return = nil

96
app/mailboxes/reply_mailbox.rb
View File

@@ -1,88 +1,38 @@
class ReplyMailbox < ApplicationMailbox
attr_accessor :conversation_uuid, :processed_mail
attr_accessor :conversation, :processed_mail
# Last part is the regex for the UUID
# Eg: email should be something like : reply+6bdc3f4d-0bec-4515-a284-5d916fdde489@domain.com
EMAIL_PART_PATTERN = /^reply\+([0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12})$/i
before_processing :conversation_uuid_from_to_address,
:find_relative_conversation
before_processing :find_conversation
def process
return if @conversation.blank?
# Return early if no conversation was found (e.g., notification emails, suspended accounts)
return unless @conversation
decorate_mail
create_message
add_attachments_to_message
# Wrap everything in a transaction to ensure atomicity
# This prevents orphan conversations if message/attachment creation fails
# and ensures idempotency on job retry (conversation won't be duplicated)
ActiveRecord::Base.transaction do
persist_conversation_if_needed
decorate_mail
create_message
add_attachments_to_message
end
end
private
def find_relative_conversation
if @conversation_uuid
find_conversation_with_uuid
elsif mail.in_reply_to.present?
find_conversation_with_in_reply_to
end
def find_conversation
@conversation = Mailbox::ConversationFinder.new(mail).find
# Log when email is rejected
Rails.logger.info "Email #{mail.message_id} rejected - no conversation found" unless @conversation
end
def conversation_uuid_from_to_address
@mail = MailPresenter.new(mail)
def persist_conversation_if_needed
# Save the conversation if it's a new record (from NewConversationStrategy)
# We persist here instead of in the strategy to maintain transaction integrity
return unless @conversation.new_record?
return if @mail.mail_receiver.blank?
@mail.mail_receiver.each do |email|
username = email.split('@')[0]
match_result = username.match(ApplicationMailbox::REPLY_EMAIL_UUID_PATTERN)
if match_result
@conversation_uuid = match_result.captures
break
end
end
@conversation_uuid
end
# find conversation uuid from below pattern
# reply+<conversation-uuid>@<mailer-domain.com>
def find_conversation_with_uuid
@conversation = Conversation.find_by(uuid: conversation_uuid)
validate_resource @conversation
end
def find_conversation_by_uuid(match_result)
@conversation_uuid = match_result.captures[0]
find_conversation_with_uuid
end
def find_conversation_by_message_id(in_reply_to)
@message = Message.find_by(source_id: in_reply_to)
@conversation = @message.conversation if @message.present?
@conversation_uuid = @conversation.uuid if @conversation.present?
end
# find conversation uuid from below pattern
# <conversation/#{@conversation.uuid}/messages/#{@messages&.last&.id}@#{@account.inbound_email_domain}>
def find_conversation_with_in_reply_to
match_result = nil
in_reply_to_addresses = mail.in_reply_to
in_reply_to_addresses = [in_reply_to_addresses] if in_reply_to_addresses.is_a?(String)
in_reply_to_addresses.each do |in_reply_to|
match_result = in_reply_to.match(::ApplicationMailbox::CONVERSATION_MESSAGE_ID_PATTERN)
break if match_result
end
find_by_in_reply_to_addresses(match_result, in_reply_to_addresses)
end
def find_by_in_reply_to_addresses(match_result, in_reply_to_addresses)
find_conversation_by_uuid(match_result) if match_result
find_conversation_by_message_id(in_reply_to_addresses) if @conversation.blank?
end
def validate_resource(resource)
Rails.logger.error "[App::Mailboxes::ReplyMailbox] Email conversation with uuid: #{conversation_uuid} not found" if resource.nil?
resource
@conversation.save!
Rails.logger.info "Created new conversation #{@conversation.id} for email #{mail.message_id}"
end
def decorate_mail

94
app/mailboxes/support_mailbox.rb
View File

@@ -1,94 +0,0 @@
class SupportMailbox < ApplicationMailbox
include IncomingEmailValidityHelper
attr_accessor :channel, :account, :inbox, :conversation, :processed_mail
before_processing :find_channel,
:load_account,
:load_inbox,
:decorate_mail
def process
Rails.logger.info "Processing email #{mail.message_id} from #{original_sender_email} to #{mail.to} with subject #{mail.subject}"
# Skip processing email if it belongs to any of the edge cases
return unless incoming_email_from_valid_email?
ActiveRecord::Base.transaction do
find_or_create_contact
find_or_create_conversation
create_message
add_attachments_to_message
end
end
private
def find_channel
find_channel_with_to_mail if @channel.blank?
raise 'Email channel/inbox not found' if @channel.nil?
@channel
end
def find_channel_with_to_mail
@channel = EmailChannelFinder.new(mail).perform
end
def load_account
@account = @channel.account
end
def load_inbox
@inbox = @channel.inbox
end
def decorate_mail
@processed_mail = MailPresenter.new(mail, @account)
end
def find_conversation_by_in_reply_to
return if in_reply_to.blank?
@account.conversations.where("additional_attributes->>'in_reply_to' = ?", in_reply_to).first
end
def in_reply_to
mail['In-Reply-To'].try(:value)
end
def original_sender_email
@processed_mail.original_sender&.downcase
end
def find_or_create_conversation
@conversation = find_conversation_by_in_reply_to || ::Conversation.create!({
account_id: @account.id,
inbox_id: @inbox.id,
contact_id: @contact.id,
contact_inbox_id: @contact_inbox.id,
additional_attributes: {
in_reply_to: in_reply_to,
source: 'email',
auto_reply: @processed_mail.auto_reply?,
mail_subject: @processed_mail.subject,
initiated_at: {
timestamp: Time.now.utc
}
}
})
end
def find_or_create_contact
@contact = @inbox.contacts.from_email(original_sender_email)
if @contact.present?
@contact_inbox = ContactInbox.find_by(inbox: @inbox, contact: @contact)
else
create_contact
end
end
def identify_contact_name
processed_mail.sender_name || processed_mail.from.first.split('@').first
end
end

29
app/services/mailbox/conversation_finder.rb Normal file
View File

@@ -0,0 +1,29 @@
class Mailbox::ConversationFinder
DEFAULT_STRATEGIES = [
Mailbox::ConversationFinderStrategies::ReceiverUuidStrategy,
Mailbox::ConversationFinderStrategies::InReplyToStrategy,
Mailbox::ConversationFinderStrategies::ReferencesStrategy,
Mailbox::ConversationFinderStrategies::NewConversationStrategy
].freeze
def initialize(mail, strategies: DEFAULT_STRATEGIES)
@mail = mail
@strategies = strategies
end
def find
@strategies.each do |strategy_class|
conversation = strategy_class.new(@mail).find
next unless conversation
strategy_name = strategy_class.name.demodulize.underscore
Rails.logger.info "Conversation found via #{strategy_name} strategy"
return conversation
end
# Should not reach here if NewConversationStrategy is in the chain
Rails.logger.error 'No conversation found via any strategy (NewConversationStrategy missing?)'
nil
end
end

13
app/services/mailbox/conversation_finder_strategies/base_strategy.rb Normal file
View File

@@ -0,0 +1,13 @@
class Mailbox::ConversationFinderStrategies::BaseStrategy
attr_reader :mail
def initialize(mail)
@mail = mail
end
# Returns Conversation or nil
# Subclasses must implement this method
def find
raise NotImplementedError, "#{self.class} must implement #find"
end
end

48
app/services/mailbox/conversation_finder_strategies/in_reply_to_strategy.rb Normal file
View File

@@ -0,0 +1,48 @@
class Mailbox::ConversationFinderStrategies::InReplyToStrategy < Mailbox::ConversationFinderStrategies::BaseStrategy
# Patterns from ApplicationMailbox
MESSAGE_PATTERN = %r{conversation/([a-zA-Z0-9-]+)/messages/(\d+)@}
# FALLBACK_PATTERN is used when building In-Reply-To headers in ConversationReplyMailer
# when there's no actual message to reply to (see app/mailers/conversation_reply_mailer.rb#in_reply_to_email).
# This happens when:
# - A conversation is started by an agent (no incoming message yet)
# - The conversation originated from a non-email channel (widget, WhatsApp, etc.) but is now using email
# - The incoming message doesn't have email metadata with a message_id
# In these cases, we use a conversation-level identifier instead of a message-level one.
FALLBACK_PATTERN = %r{account/(\d+)/conversation/([a-zA-Z0-9-]+)@}
def find
return nil if mail.in_reply_to.blank?
in_reply_to_addresses = Array.wrap(mail.in_reply_to)
in_reply_to_addresses.each do |in_reply_to|
# Try extracting UUID from patterns
uuid = extract_uuid_from_patterns(in_reply_to)
if uuid
conversation = Conversation.find_by(uuid: uuid)
return conversation if conversation
end
# Try finding by message source_id
message = Message.find_by(source_id: in_reply_to)
return message.conversation if message&.conversation
end
nil
end
private
def extract_uuid_from_patterns(message_id)
# Try message-specific pattern first
match = MESSAGE_PATTERN.match(message_id)
return match[1] if match
# Try conversation fallback pattern
match = FALLBACK_PATTERN.match(message_id)
return match[2] if match
nil
end
end

83
app/services/mailbox/conversation_finder_strategies/new_conversation_strategy.rb Normal file
View File

@@ -0,0 +1,83 @@
class Mailbox::ConversationFinderStrategies::NewConversationStrategy < Mailbox::ConversationFinderStrategies::BaseStrategy
include MailboxHelper
include IncomingEmailValidityHelper
attr_accessor :processed_mail, :account, :inbox, :contact, :contact_inbox, :conversation, :channel
def initialize(mail)
super(mail)
@channel = EmailChannelFinder.new(mail).perform
return unless @channel
@account = @channel.account
@inbox = @channel.inbox
@processed_mail = MailPresenter.new(mail, @account)
end
# This strategy prepares a new conversation but doesn't persist it yet.
# Why we don't use create! here:
# - Avoids orphan conversations if message/attachment creation fails later
# - Prevents duplicate conversations on job retry (no idempotency issue)
# - Follows the pattern from old SupportMailbox where everything was in one transaction
# The actual persistence happens in ReplyMailbox within a transaction that includes message creation.
def find
return nil unless @channel # No valid channel found
return nil unless incoming_email_from_valid_email? # Skip edge cases
# Check if conversation already exists by in_reply_to
existing_conversation = find_conversation_by_in_reply_to
return existing_conversation if existing_conversation
# Prepare contact (persisted) and build conversation (not persisted)
find_or_create_contact
build_conversation
end
private
def find_or_create_contact
@contact = @inbox.contacts.from_email(original_sender_email)
if @contact.present?
@contact_inbox = ContactInbox.find_by(inbox: @inbox, contact: @contact)
else
create_contact
end
end
def original_sender_email
@processed_mail.original_sender&.downcase
end
def identify_contact_name
@processed_mail.sender_name || @processed_mail.from.first.split('@').first
end
def build_conversation
# Build but don't persist - ReplyMailbox will save in transaction with message
@conversation = ::Conversation.new(
account_id: @account.id,
inbox_id: @inbox.id,
contact_id: @contact.id,
contact_inbox_id: @contact_inbox.id,
additional_attributes: {
in_reply_to: in_reply_to,
source: 'email',
auto_reply: @processed_mail.auto_reply?,
mail_subject: @processed_mail.subject,
initiated_at: {
timestamp: Time.now.utc
}
}
)
end
def in_reply_to
mail['In-Reply-To'].try(:value)
end
def find_conversation_by_in_reply_to
return if in_reply_to.blank?
@account.conversations.where("additional_attributes->>'in_reply_to' = ?", in_reply_to).first
end
end

26
app/services/mailbox/conversation_finder_strategies/receiver_uuid_strategy.rb Normal file
View File

@@ -0,0 +1,26 @@
class Mailbox::ConversationFinderStrategies::ReceiverUuidStrategy < Mailbox::ConversationFinderStrategies::BaseStrategy
# Pattern from ApplicationMailbox::REPLY_EMAIL_UUID_PATTERN
UUID_PATTERN = /^reply\+([0-9a-f]{8}\b-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-\b[0-9a-f]{12})$/i
def find
uuid = extract_uuid_from_receivers
return nil unless uuid
Conversation.find_by(uuid: uuid)
end
private
def extract_uuid_from_receivers
mail_presenter = MailPresenter.new(mail)
return nil if mail_presenter.mail_receiver.blank?
mail_presenter.mail_receiver.each do |email|
username = email.split('@').first
match = username.match(UUID_PATTERN)
return match[1] if match
end
nil
end
end

59
app/services/mailbox/conversation_finder_strategies/references_strategy.rb Normal file
View File

@@ -0,0 +1,59 @@
class Mailbox::ConversationFinderStrategies::ReferencesStrategy < Mailbox::ConversationFinderStrategies::BaseStrategy
# Patterns from ApplicationMailbox
MESSAGE_PATTERN = %r{conversation/([a-zA-Z0-9-]+)/messages/(\d+)@}
# FALLBACK_PATTERN is used when building References headers in ConversationReplyMailer
# when there's no actual message to reply to (see app/mailers/conversation_reply_mailer.rb#in_reply_to_email).
# This happens when:
# - A conversation is started by an agent (no incoming message yet)
# - The conversation originated from a non-email channel (widget, WhatsApp, etc.) but is now using email
# - The incoming message doesn't have email metadata with a message_id
# In these cases, we use a conversation-level identifier instead of a message-level one.
FALLBACK_PATTERN = %r{account/(\d+)/conversation/([a-zA-Z0-9-]+)@}
def initialize(mail)
super(mail)
# Get channel once upfront to use for scoped queries
@channel = EmailChannelFinder.new(mail).perform
end
def find
return nil if mail.references.blank?
return nil unless @channel # No valid channel found
references = Array.wrap(mail.references)
references.each do |reference|
conversation = find_conversation_from_reference(reference)
return conversation if conversation
end
nil
end
private
def find_conversation_from_reference(reference)
# Try extracting UUID from patterns
uuid = extract_uuid_from_patterns(reference)
if uuid
# Query scoped to inbox - prevents cross-account/cross-inbox matches at database level
conversation = Conversation.find_by(uuid: uuid, inbox_id: @channel.inbox.id)
return conversation if conversation
end
# We scope to the inbox, that way we filter out messages and conversations that don't belong to the channel
message = Message.find_by(source_id: reference, inbox_id: @channel.inbox.id)
message&.conversation
end
def extract_uuid_from_patterns(message_id)
match = MESSAGE_PATTERN.match(message_id)
return match[1] if match
match = FALLBACK_PATTERN.match(message_id)
return match[2] if match
nil
end
end