gitlab-email_handler 0.0.0 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9959523f39476ee9ef18e9434e6b53f06cfee59ed10fc06ea3c58010fc96bfdb
-  data.tar.gz: 3bf21681b7943e5071436edb0ebe92a11cdc727703f8b3f799a104270c0d0a69
+  metadata.gz: a5f1f3376c9afa7036243ffa5c2e9ebe5916b516aa0493126b8105a3d20b3835
+  data.tar.gz: 2efd5e7c9c09d88ace45cf77480fdebf8236956d8aaf616ce1413ff644c5757f
 SHA512:
-  metadata.gz: 17f60936562182791d348d2e764c0a62d73d5feed7b6ec7a839f363126b34545c8c3942d1bb77ff1a8ef11dbd3852c36e453970232f5ff0193d0f5c8fa2c185a
-  data.tar.gz: a6d1434a975d8242b6b87536ecf5b5208a6ed0d054b85ed13b8cb5b9a7bde95e7e00cb6d63b017e1b95062ce3aa0a262f7e888c9ac7921e416fd930f1ebc9eda
+  metadata.gz: 4c0f7eb203d86315769156dda59a9d20d6fa216a3524d62aacee97bc2408451b7b2d69994c8cbf4849cc9d154eba9a5f128dc8b1dae83a20b03917fcf7502765
+  data.tar.gz: 005f7845096ad4b55bbde87fa6bbe3e380bdc43ced7db791a69438c13b9598820ffed3225416c73cf93257adb23a688182efd17f28248d6cd755464b63652b9e

data/lib/gitlab/email_handler/custom_email.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative 'reply_key'
+
+module Gitlab
+  module EmailHandler
+    # Helpers for recognising and normalising custom Service Desk email
+    # addresses (e.g. support@acme.com). These mirror the parsing in
+    # Gitlab::Email::ServiceDesk::CustomEmail but without any database access -
+    # whether an address is actually a registered custom email is confirmed by
+    # the Topology Service (see CellRouter).
+    module CustomEmail
+      VERIFICATION_SUBADDRESS = '+verify'
+
+      # Matches a reply address like "support+<reply_key>@acme.com". The full
+      # reply key spans everything between the first "+" and the "@"; we then
+      # validate that span against the reply-key format. We capture by position
+      # (not a named group) to avoid colliding with the named groups inside
+      # FULL_REPLY_KEY_REGEX.
+      FULL_REPLY_KEY_ANCHORED = /\A#{ReplyKey::FULL_REPLY_KEY_REGEX}\z/
+      REPLY_ADDRESS_REGEX = /\A(?<base>[^+]+)\+(?<full_key>[^@]+)@(?<domain>.+)\z/
+
+      # Loose email shape check. Custom emails are arbitrary addresses, so this
+      # only filters out obvious non-addresses before asking the Topology
+      # Service.
+      EMAIL_REGEX = /\A[^@\s]+@[^@\s]+\.[^@\s]+\z/
+
+      module_function
+
+      # Returns the base custom email address for a candidate recipient, with
+      # any "+verify" or "+<reply_key>" sub-addressing removed, or nil if the
+      # value doesn't look like an email address.
+      #
+      #   support@acme.com            -> support@acme.com
+      #   support+verify@acme.com     -> support@acme.com
+      #   support+<reply_key>@acme.com -> support@acme.com
+      def base_address(address)
+        value = address.to_s.strip
+        return unless EMAIL_REGEX.match?(value)
+
+        match = reply_address_match(value)
+        return "#{match[:base]}@#{match[:domain]}" if match
+
+        value.sub(VERIFICATION_SUBADDRESS, '')
+      end
+
+      # Extracts the reply key from a custom email reply address, or nil.
+      #   support+<reply_key>@acme.com -> <reply_key>
+      def reply_key(address)
+        reply_address_match(address)&.[](:full_key)
+      end
+
+      # Matches a reply address and validates the embedded key against the
+      # reply-key format, returning the MatchData or nil. Centralising the
+      # match avoids running REPLY_ADDRESS_REGEX twice.
+      def reply_address_match(address)
+        match = REPLY_ADDRESS_REGEX.match(address.to_s)
+        return unless match
+        return unless FULL_REPLY_KEY_ANCHORED.match?(match[:full_key])
+
+        match
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/identification.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative 'reply_key'
+require_relative 'target'
+
+module Gitlab
+  module EmailHandler
+    # Result of parsing an incoming email key. Carries the handler that matched
+    # and the captures relevant to that handler. The captures are handler
+    # specific (project_id, project_path, reply_key, namespace_id, etc.).
+    #
+    # `#target` returns the identified Target (the resource that owns the email),
+    # or nil when the email can't be identified (legacy reply keys without an
+    # encoded namespace):
+    #
+    #   - Target.project_id   - project id encoded directly in the key
+    #   - Target.namespace_id - decoded offline from a partitioned reply key
+    #   - Target.route        - full project/group path (located by its top-level
+    #                           namespace)
+    #   - Target.service_desk_project_key_address_slug
+    #                         - opaque service desk project key, matched verbatim
+    #                           against the claimed
+    #                           service_desk_settings.project_key_address_slug
+    #   - nil                 - cannot be identified
+    Identification = Data.define(:handler, :attributes) do
+      def [](key)
+        attributes[key]
+      end
+
+      def project_id
+        attributes[:project_id]
+      end
+
+      def project_path
+        attributes[:project_path]
+      end
+
+      def project_slug
+        attributes[:project_slug]
+      end
+
+      def incoming_email_token
+        attributes[:incoming_email_token]
+      end
+
+      # Decodes the base36 namespace_id encoded in partitioned reply keys.
+      # Returns nil for legacy reply keys and partitioned keys that don't
+      # encode a namespace id.
+      def decoded_namespace_id
+        encoded = attributes[:namespace_id]
+        return unless encoded
+
+        encoded.to_i(ReplyKey::INTEGER_CONVERT_BASE)
+      end
+
+      # The identified Target for this email, or nil when it can't be identified.
+      def target
+        namespace_id = decoded_namespace_id
+
+        if namespace_id
+          Target.namespace_id(namespace_id)
+        elsif project_id
+          Target.project_id(project_id)
+        elsif project_path
+          Target.route(project_path)
+        elsif attributes[:project_key_address_slug]
+          Target.service_desk_project_key_address_slug(attributes[:project_key_address_slug])
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/identifier.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative 'matchers/create_note'
+require_relative 'matchers/create_issue'
+require_relative 'matchers/create_note_on_issuable'
+require_relative 'matchers/unsubscribe'
+require_relative 'matchers/create_merge_request'
+require_relative 'matchers/service_desk'
+
+module Gitlab
+  module EmailHandler
+    # Identifies which handler an incoming email key belongs to by trying each
+    # matcher in the same precedence order as
+    # Gitlab::Email::Handler.load_handlers.
+    module Identifier
+      # Order mirrors Gitlab::Email::Handler.load_handlers.
+      MATCHERS = [
+        Matchers::CreateNote,
+        Matchers::CreateIssue,
+        Matchers::CreateNoteOnIssuable,
+        Matchers::Unsubscribe,
+        Matchers::CreateMergeRequest,
+        Matchers::ServiceDesk
+      ].freeze
+
+      class << self
+        def matchers
+          @matchers ||= MATCHERS.map(&:new)
+        end
+
+        # @param mail_key [String]
+        # @return [Gitlab::EmailHandler::Identification, nil]
+        def call(mail_key)
+          return if mail_key.nil?
+
+          matchers.each do |matcher|
+            result = matcher.match(mail_key)
+            return result if result
+          end
+
+          nil
+        end
+
+        # Convenience: returns an Identification for a specific handler only.
+        # Used by the GitLab handlers which already know their own type.
+        def for_handler(handler_name, mail_key)
+          matcher = matchers.find { |m| m.handler_name == handler_name }
+          matcher&.match(mail_key)
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/mail_key.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module EmailHandler
+    # Extracts the mail key from an incoming email's headers.
+    #
+    # This is the single source of truth for *how* an incoming email is scanned
+    # for a mail key: the order in which recipient headers (and the references
+    # fallback) are tried, how a wildcard address is parsed into a key, and how a
+    # fallback message id is parsed. Both the GitLab application
+    # (Gitlab::Email::Receiver) and the standalone mail_room service consume this
+    # so they can never disagree on which key an email resolves to.
+    #
+    # The module is pure and config-free: callers pass the wildcard address and
+    # the GitLab host as arguments rather than reading them from any global
+    # configuration.
+    #
+    # Callers own *what* to do with each candidate (the application layers in
+    # database-backed Service Desk custom email lookups; the mail_room service
+    # maps each candidate to a routing Target), but never the ordering. They pass
+    # a block to `each_candidate`; the first non-nil value the block returns wins
+    # and iteration stops, mirroring the original short-circuiting behavior.
+    module MailKey
+      # Recipient sources, in the precedence the GitLab application has always
+      # used. `:references` is the message-id fallback and is tried after the
+      # primary `:to` header but before the remaining headers. `:received`
+      # extracts recipients from the Received headers.
+      RECIPIENT_HEADERS = %i[
+        delivered_to x_delivered_to envelope_to x_envelope_to received x_original_to x_forwarded_to cc
+      ].freeze
+
+      # Extracts the recipient address out of a `Received` header, e.g.
+      #   Received: from x by y for <incoming+key@host>; <date>
+      RECEIVED_HEADER_REGEX = /for\s+<([^<]+)>/
+
+      WILDCARD_PLACEHOLDER = '%{key}'
+
+      # A single mail key candidate.
+      #
+      # - source: the header the candidate came from (e.g. :to, :references)
+      # - value:  the raw recipient address, or message id for :references
+      # - key:    the offline-parsed mail key for this candidate, or nil
+      Candidate = Data.define(:source, :value, :key)
+
+      module_function
+
+      # Yields each mail key candidate, in precedence order, to the given block.
+      # The first non-nil block result is returned and iteration stops. Returns
+      # nil when no candidate is found or the block matches nothing.
+      #
+      # @param mail [Mail::Message]
+      # @param wildcard_address [String, nil] the configured incoming/service
+      #   desk address containing the `%{key}` placeholder
+      # @param gitlab_host [String, nil] the GitLab host, used to parse the
+      #   references message-id fallback
+      # @yieldparam candidate [Candidate]
+      # @return the first non-nil block result, or nil
+      def each_candidate(mail, wildcard_address:, gitlab_host:)
+        return unless block_given?
+
+        # 1. The primary To header.
+        addresses(mail, :to).each do |address|
+          result = yield Candidate.new(source: :to, value: address, key: key_from_address(address, wildcard_address))
+          return result if result
+        end
+
+        # 2. The references message-id fallback.
+        reference_message_ids(mail).each do |mail_id|
+          result = yield Candidate.new(
+            source: :references,
+            value: mail_id,
+            key: key_from_fallback_message_id(mail_id, gitlab_host)
+          )
+          return result if result
+        end
+
+        # 3. The remaining recipient headers.
+        RECIPIENT_HEADERS.each do |source|
+          addresses(mail, source).each do |address|
+            result = yield Candidate.new(source: source, value: address,
+              key: key_from_address(address, wildcard_address))
+            return result if result
+          end
+        end
+
+        nil
+      end
+
+      # Parses a mail key out of a recipient address using the wildcard address.
+      #
+      #   wildcard "incoming+%{key}@host", address "incoming+abc@host" => "abc"
+      #
+      # @return [String, nil]
+      def key_from_address(address, wildcard_address)
+        regex = address_regex(wildcard_address)
+        return unless regex
+
+        address.to_s.match(regex)&.[](1)
+      end
+
+      # Parses a mail key out of a fallback message id of the form
+      # `reply-<key>@<gitlab_host>`.
+      #
+      # @return [String, nil]
+      def key_from_fallback_message_id(mail_id, gitlab_host)
+        return unless gitlab_host
+
+        mail_id.to_s[/\Areply-(.+)@#{Regexp.escape(gitlab_host)}\z/, 1]
+      end
+
+      # Splits a raw References header value into individual message ids. Handles
+      # clients that join references with commas (e.g. Microsoft Exchange, iOS).
+      #
+      # @return [Array<String>]
+      def scan_fallback_references(references)
+        # Looks for each <...>
+        references.to_s.scan(/(?!<)[^<>]+(?=>)/)
+      end
+
+      # The addresses for a recipient source, normalized to strings.
+      #
+      # `:to` and `:cc` use the Mail::Message readers, which return arrays of
+      # individual address strings. Every other header is read as a raw field via
+      # `mail[header]`, matching how Gitlab::Email::Receiver has always read them.
+      def addresses(mail, source)
+        case source
+        when :to then Array(mail.to)
+        when :cc then Array(mail.cc)
+        when :received then received_recipients(mail)
+        else
+          Array(mail[source]).map { |item| item.is_a?(Mail::Field) ? item.value : item.to_s }
+        end
+      end
+
+      def received_recipients(mail)
+        Array(mail[:received]).filter_map { |header| header.value[RECEIVED_HEADER_REGEX, 1] }
+      end
+
+      def reference_message_ids(mail)
+        references = mail.references
+
+        case references
+        when Array then references
+        when String then scan_fallback_references(references)
+        else []
+        end
+      end
+
+      def address_regex(wildcard_address)
+        return unless wildcard_address
+
+        escaped = Regexp.escape(wildcard_address).sub(Regexp.escape(WILDCARD_PLACEHOLDER), '(.+)')
+        /\A<?#{escaped}>?\z/
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/matchers/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative '../reply_key'
+require_relative '../identification'
+
+module Gitlab
+  module EmailHandler
+    module Matchers
+      # Base class for handler matchers. Each matcher mirrors exactly one email
+      # handler's mail key parsing and the database-free portion of its
+      # `can_handle?` logic. Matchers never touch the database or the network.
+      class Base
+        # @param mail_key [String]
+        # @return [Gitlab::EmailHandler::Identification, nil]
+        def match(mail_key)
+          raise NotImplementedError
+        end
+
+        # The handler name this matcher corresponds to (e.g. :create_issue).
+        # @return [Symbol]
+        def handler_name
+          raise NotImplementedError
+        end
+
+        private
+
+        def identification(**attributes)
+          Identification.new(handler: handler_name, attributes: attributes)
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/matchers/create_issue.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Gitlab
+  module EmailHandler
+    module Matchers
+      # Mirrors Gitlab::Email::Handler::CreateIssueHandler.
+      #   incoming+gitlab-org-gitlab-ce-20-Author_Token-issue@incoming.gitlab.com
+      #   incoming+gitlab-org/gitlab-ce+Author_Token@incoming.gitlab.com (legacy)
+      class CreateIssue < Base
+        HANDLER_REGEX = /\A#{ReplyKey::HANDLER_ACTION_BASE_REGEX}-(?<incoming_email_token>.+)-issue\z/
+        HANDLER_REGEX_LEGACY = /\A(?<project_path>[^+]*)\+(?<incoming_email_token>.*)\z/
+
+        def match(mail_key)
+          key = mail_key.to_s
+
+          matched = HANDLER_REGEX.match(key) unless mail_key&.include?('/')
+          if matched
+            return identification(
+              project_slug: matched[:project_slug],
+              project_id: matched[:project_id]&.to_i,
+              incoming_email_token: matched[:incoming_email_token]
+            )
+          end
+
+          matched = HANDLER_REGEX_LEGACY.match(key)
+          return unless matched
+
+          project_path = matched[:project_path]
+          incoming_email_token = matched[:incoming_email_token]
+          return unless can_handle_legacy_format?(project_path, incoming_email_token, key)
+
+          identification(
+            project_path: project_path,
+            incoming_email_token: incoming_email_token
+          )
+        end
+
+        def handler_name
+          :create_issue
+        end
+
+        private
+
+        def can_handle_legacy_format?(project_path, incoming_email_token, mail_key)
+          project_path &&
+            incoming_email_token &&
+            !incoming_email_token.include?('+') &&
+            !mail_key.include?(ReplyKey::UNSUBSCRIBE_SUFFIX_LEGACY)
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/matchers/create_merge_request.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Gitlab
+  module EmailHandler
+    module Matchers
+      # Mirrors Gitlab::Email::Handler::CreateMergeRequestHandler.
+      #   incoming+gitlab-org-gitlab-ce-20-Author_Token-merge-request@incoming.gitlab.com
+      #   incoming+gitlab-org/gitlab-ce+merge-request+Author_Token@incoming.gitlab.com (legacy)
+      class CreateMergeRequest < Base
+        HANDLER_REGEX = /\A#{ReplyKey::HANDLER_ACTION_BASE_REGEX}-(?<incoming_email_token>.+)-merge-request\z/
+        HANDLER_REGEX_LEGACY = /\A(?<project_path>[^+]*)\+merge-request\+(?<incoming_email_token>.*)/
+
+        def match(mail_key)
+          key = mail_key.to_s
+
+          matched = HANDLER_REGEX.match(key) unless mail_key&.include?('/')
+          if matched
+            return identification(
+              project_slug: matched[:project_slug],
+              project_id: matched[:project_id]&.to_i,
+              incoming_email_token: matched[:incoming_email_token]
+            )
+          end
+
+          matched = HANDLER_REGEX_LEGACY.match(key)
+          return unless matched
+
+          identification(
+            project_path: matched[:project_path],
+            incoming_email_token: matched[:incoming_email_token]
+          )
+        end
+
+        def handler_name
+          :create_merge_request
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/matchers/create_note.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Gitlab
+  module EmailHandler
+    module Matchers
+      # Mirrors Gitlab::Email::Handler::CreateNoteHandler.
+      #   incoming+<reply_key>@incoming.gitlab.com
+      class CreateNote < Base
+        HANDLER_REGEX = /\A#{ReplyKey::FULL_REPLY_KEY_REGEX}\z/
+
+        def match(mail_key)
+          matched = HANDLER_REGEX.match(mail_key.to_s)
+          return unless matched
+
+          identification(
+            reply_key: matched[:reply_key],
+            namespace_id: matched[:namespace_id],
+            legacy_key: matched[:legacy_key]
+          )
+        end
+
+        def handler_name
+          :create_note
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/matchers/create_note_on_issuable.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Gitlab
+  module EmailHandler
+    module Matchers
+      # Mirrors Gitlab::Email::Handler::CreateNoteOnIssuableHandler.
+      #   incoming+gitlab-org-gitlab-ce-20-Author_Token-issue-34@incoming.gitlab.com
+      class CreateNoteOnIssuable < Base
+        HANDLER_REGEX =
+          /\A#{ReplyKey::HANDLER_ACTION_BASE_REGEX}-(?<incoming_email_token>.+)-issue-(?<issuable_iid>\d+)\z/
+
+        def match(mail_key)
+          matched = HANDLER_REGEX.match(mail_key.to_s)
+          return unless matched
+
+          identification(
+            project_slug: matched[:project_slug],
+            project_id: matched[:project_id]&.to_i,
+            incoming_email_token: matched[:incoming_email_token],
+            issuable_iid: matched[:issuable_iid]&.to_i
+          )
+        end
+
+        def handler_name
+          :create_note_on_issuable
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/matchers/service_desk.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Gitlab
+  module EmailHandler
+    module Matchers
+      # Mirrors Gitlab::Email::Handler::ServiceDeskHandler (parsing portion).
+      #   incoming+gitlab-org-gitlab-ce-20-issue-@incoming.gitlab.com
+      #   incoming+gitlab-org/gitlab-ce@incoming.gitlab.com (legacy)
+      #   support+gitlab-org-gitlab-ce-abc123_def@service-desk.gitlab.com (project key)
+      #
+      # The opaque project key form (slug-key) is stored whole in
+      # `service_desk_settings.project_key_address_slug` and claimed as unique
+      # in the Topology Service, so it is identifiable without a database
+      # lookup. Resolving which project it belongs to remains an app-side
+      # concern (Project.with_service_desk_key). The custom email form is
+      # resolvable via a Topology Service lookup.
+      class ServiceDesk < Base
+        HANDLER_REGEX = /\A#{ReplyKey::HANDLER_ACTION_BASE_REGEX}-issue-\z/
+        HANDLER_REGEX_LEGACY = /\A(?<project_path>[^+]*)\z/
+        # Parses an opaque service desk key of the form `<slug>-<key>`. The key
+        # is resolved against the database (Project.with_service_desk_key) so
+        # this stays an app-side concern, but the pattern itself lives here to
+        # keep all email key parsing in one place.
+        PROJECT_KEY_PATTERN = /\A(?<slug>.+)-(?<key>[a-z0-9_]+)\z/
+
+        def match(mail_key)
+          key = mail_key.to_s
+
+          matched = HANDLER_REGEX.match(key) unless mail_key&.include?('/')
+          if matched
+            return identification(
+              project_slug: matched[:project_slug],
+              project_id: matched[:project_id]&.to_i
+            )
+          end
+
+          matched = HANDLER_REGEX_LEGACY.match(key)
+          if matched && can_handle_legacy_format?(matched[:project_path], key)
+            return identification(project_path: matched[:project_path])
+          end
+
+          match_project_key(key)
+        end
+
+        def handler_name
+          :service_desk
+        end
+
+        private
+
+        def can_handle_legacy_format?(project_path, mail_key)
+          project_path&.include?('/') && !mail_key.include?('+')
+        end
+
+        # An opaque `<slug>-<key>` project key. The whole concatenated string is
+        # what `service_desk_settings.project_key_address_slug` stores and the
+        # Topology Service claims, so no splitting is needed: both parts are
+        # already lowercase by validation, and the composite value is matched
+        # verbatim.
+        def match_project_key(key)
+          return unless PROJECT_KEY_PATTERN.match?(key)
+
+          identification(project_key_address_slug: key)
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/matchers/unsubscribe.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+
+module Gitlab
+  module EmailHandler
+    module Matchers
+      # Mirrors Gitlab::Email::Handler::UnsubscribeHandler.
+      #   incoming+<reply_key>-unsubscribe@incoming.gitlab.com
+      #   incoming+<reply_key>+unsubscribe@incoming.gitlab.com (legacy)
+      class Unsubscribe < Base
+        HANDLER_REGEX_FOR = ->(suffix) {
+          /\A(?<reply_token>#{ReplyKey::FULL_REPLY_KEY_REGEX})#{Regexp.escape(suffix)}\z/
+        }.freeze
+        HANDLER_REGEX = HANDLER_REGEX_FOR.call(ReplyKey::UNSUBSCRIBE_SUFFIX).freeze
+        HANDLER_REGEX_LEGACY = HANDLER_REGEX_FOR.call(ReplyKey::UNSUBSCRIBE_SUFFIX_LEGACY).freeze
+
+        def match(mail_key)
+          key = mail_key.to_s
+          matched = HANDLER_REGEX.match(key) || HANDLER_REGEX_LEGACY.match(key)
+          return unless matched
+
+          identification(
+            reply_token: matched[:reply_token],
+            reply_key: matched[:reply_key],
+            namespace_id: matched[:namespace_id],
+            legacy_key: matched[:legacy_key]
+          )
+        end
+
+        def handler_name
+          :unsubscribe
+        end
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/reply_key.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module EmailHandler
+    # Single source of truth for the regular expressions and constants used to
+    # parse incoming email keys. These were previously defined inline in
+    # `SentNotification` and the email handlers. Keeping them here lets both the
+    # GitLab application and the standalone mail_room identification service
+    # share the exact same parsing rules.
+    module ReplyKey
+      REPLY_KEY_BYTE_SIZE = 16
+      INTEGER_CONVERT_BASE = 36
+      BASE36_REGEX = /[0-9a-z]/
+      NAMESPACE_REGEX = /(?:-(?<namespace_id>#{BASE36_REGEX}{1,13}))?/
+      # Email reply key is in the form: <base36-partition-id>-<base36-reply-key>-<base36-namespace-id>
+      PARTITIONED_REPLY_KEY_REGEX =
+        /(?<partition>#{BASE36_REGEX}{1,4})-(?<reply_key>#{BASE36_REGEX}{25})#{NAMESPACE_REGEX}/
+      LEGACY_REPLY_KEY_REGEX = /(?<legacy_key>[a-f\d]{32})/
+      FULL_REPLY_KEY_REGEX = /(?:(#{LEGACY_REPLY_KEY_REGEX})|(#{PARTITIONED_REPLY_KEY_REGEX}))/
+
+      # Base regex shared by handlers that encode `<project_slug>-<project_id>` in
+      # the mail key.
+      HANDLER_ACTION_BASE_REGEX = /(?<project_slug>.+)-(?<project_id>\d+)/
+
+      UNSUBSCRIBE_SUFFIX = '-unsubscribe'
+      UNSUBSCRIBE_SUFFIX_LEGACY = '+unsubscribe'
+    end
+  end
+end

data/lib/gitlab/email_handler/target.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module EmailHandler
+    # The identified target of an incoming email: the kind of resource that owns
+    # it and the value that locates it. This is a plain value object with no
+    # knowledge of how the target is later resolved or routed.
+    #
+    # `kind` is one of:
+    #   :project_id, :namespace_id, :route, :service_desk_custom_email,
+    #   :service_desk_project_key_address_slug
+    Target = Data.define(:kind, :value) do
+      def self.project_id(value)
+        new(kind: :project_id, value: value)
+      end
+
+      def self.namespace_id(value)
+        new(kind: :namespace_id, value: value)
+      end
+
+      def self.route(path)
+        new(kind: :route, value: path.to_s.split('/').first)
+      end
+
+      def self.service_desk_custom_email(value)
+        new(kind: :service_desk_custom_email, value: value)
+      end
+
+      def self.service_desk_project_key_address_slug(value)
+        new(kind: :service_desk_project_key_address_slug, value: value)
+      end
+    end
+  end
+end

data/lib/gitlab/email_handler/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Gitlab
+  module EmailHandler
+    module Version
+      VERSION = "0.1.0"
+    end
+  end
+end

data/lib/gitlab/email_handler.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative 'email_handler/version'
+
+# Pure, dependency-free incoming email identification: regex parsing of mail
+# keys into a Target. No Rails, gRPC or HTTP dependencies. Resolving a Target to
+# a cell and forwarding the email are the responsibility of the consumer (the
+# mail_room service), not this gem.
+require_relative 'email_handler/reply_key'
+require_relative 'email_handler/target'
+require_relative 'email_handler/identification'
+require_relative 'email_handler/identifier'
+require_relative 'email_handler/custom_email'
+require_relative 'email_handler/mail_key'

metadata

@@ -1,14 +1,57 @@
 --- !ruby/object:Gem::Specification
 name: gitlab-email_handler
 version: !ruby/object:Gem::Version
-  version: 0.0.0
+  version: 0.1.0
 platform: ruby
 authors:
-- group::service desk
+- group::project management
+autorequire:
 bindir: bin
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
-dependencies: []
+date: 2026-10-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: gitlab-styles
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '14.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '14.0'
+- !ruby/object:Gem::Dependency
+  name: mail
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: Parses incoming email keys to identify the target handler and the resource
   (project, namespace, or route) that owns the email.
 email:
@@ -17,12 +60,29 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- lib/gitlab-email_handler.rb
-homepage: https://gitlab.com/gitlab-org/gitlab/-/tree/master/gems/gitlab-email_handler
+- lib/gitlab/email_handler.rb
+- lib/gitlab/email_handler/custom_email.rb
+- lib/gitlab/email_handler/identification.rb
+- lib/gitlab/email_handler/identifier.rb
+- lib/gitlab/email_handler/mail_key.rb
+- lib/gitlab/email_handler/matchers/base.rb
+- lib/gitlab/email_handler/matchers/create_issue.rb
+- lib/gitlab/email_handler/matchers/create_merge_request.rb
+- lib/gitlab/email_handler/matchers/create_note.rb
+- lib/gitlab/email_handler/matchers/create_note_on_issuable.rb
+- lib/gitlab/email_handler/matchers/service_desk.rb
+- lib/gitlab/email_handler/matchers/unsubscribe.rb
+- lib/gitlab/email_handler/reply_key.rb
+- lib/gitlab/email_handler/target.rb
+- lib/gitlab/email_handler/version.rb
+homepage: https://gitlab.com/gitlab-org/ruby/gems/gitlab-email_handler
 licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
+  source_code_uri: https://gitlab.com/gitlab-org/ruby/gems/gitlab-email_handler
+  changelog_uri: https://gitlab.com/gitlab-org/ruby/gems/gitlab-email_handler/-/releases
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -37,7 +97,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.5.22
+signing_key:
 specification_version: 4
 summary: Incoming email identification for GitLab
 test_files: []

data/lib/gitlab-email_handler.rb

@@ -1,3 +0,0 @@
-# frozen_string_literal: true
-
-raise "Reserved for GitLab"