cloudflare-email 0.2.0 → 0.4.0

data/lib/cloudflare/email/active_record/routing_deliveries.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "cloudflare/email/routing_analytics"
+require "cloudflare/email/active_record/outbox"
+
+module Cloudflare
+  module Email
+    module ActiveRecord
+      class RoutingDeliveryReceipt < Base
+        self.table_name = "cloudflare_email_routing_delivery_receipts"
+        belongs_to :outbound_delivery, class_name: "Cloudflare::Email::ActiveRecord::OutboundDelivery"
+        encrypts :payload_json
+        attr_readonly :account_id, :zone_id, :event_key, :outbound_delivery_id, :payload_json, :received_at
+
+        def evidence
+          RoutingAnalytics::Evidence.new(JSON.parse(payload_json))
+        rescue JSON::ParserError, TypeError
+          raise RoutingAnalytics::Error, "Stored Routing analytics evidence is malformed", cause: nil
+        end
+      end
+
+      # An opt-in delivery projection, separate from Sending webhook receipts and
+      # acceptance reconciliation. No method here can send or authorize a resend.
+      class RoutingDeliveries
+        class InvalidEvidence < RoutingAnalytics::Error; end
+        ReplayResult = Struct.new(:after_id, :processed, :errors, :finished, keyword_init: true)
+
+        class << self
+          def record(delivery:, evidence:)
+            unless evidence.is_a?(RoutingAnalytics::Evidence) && delivery.is_a?(OutboundDelivery) && delivery.persisted?
+              raise ArgumentError, "A persisted outbound delivery and RoutingAnalytics::Evidence are required"
+            end
+            if RoutingDeliveryReceipt.connection.transaction_open?
+              raise ArgumentError, "record must commit outside an existing transaction before projection"
+            end
+            validate!(delivery.reload, evidence)
+            receipt = RoutingDeliveryReceipt.create_or_find_by!(account_id: evidence.account_id, event_key: evidence.identity) do |row|
+              row.outbound_delivery = delivery
+              row.zone_id = evidence.zone_id
+              row.payload_json = JSON.generate(evidence.payload)
+              row.received_at = Time.now.utc
+            end
+            unless receipt.outbound_delivery_id == delivery.id && receipt.evidence.same_event?(evidence)
+              raise InvalidEvidence, "Routing analytics evidence identity conflict"
+            end
+            receipt
+          end
+
+          # Returns :applied (including idempotent replay). An existing terminal
+          # fact is preserved; inspect recipient.state instead of assuming delivery.
+          # Only new recipient changes invoke the same-database callback.
+          def apply(receipt)
+            unless receipt.is_a?(RoutingDeliveryReceipt) && receipt.persisted?
+              raise ArgumentError, "A persisted RoutingDeliveryReceipt is required"
+            end
+            completed = false
+            receipt.with_lock(requires_new: true) do
+              if receipt.state == "applied"
+                completed = true
+                next
+              end
+              evidence = receipt.evidence
+              unless receipt.account_id == evidence.account_id && receipt.zone_id == evidence.zone_id && receipt.event_key == evidence.identity
+                raise InvalidEvidence, "Routing analytics receipt identity mismatch"
+              end
+              delivery = receipt.outbound_delivery
+              delivery.with_lock do
+                recipient = validate!(delivery, evidence)
+                unless recipient.terminal?
+                  recipient.update!(state: "delivered", occurred_at: evidence.occurred_at, terminal: true)
+                  yield delivery, recipient if block_given?
+                end
+                receipt.update!(state: "applied", applied_at: Time.now.utc)
+                completed = true
+              end
+              # ActiveRecord::Rollback can be swallowed by the nested lock's
+              # transaction. Fail before this outer transaction can commit.
+              raise ArgumentError, "Projection rolled back instead of completing" unless completed
+            end
+            raise ArgumentError, "Projection rolled back instead of completing" unless completed
+            :applied
+          end
+
+          # Each failed receipt advances the cursor too. Persist after_id in the
+          # host job and reset it to zero after finished; discovery gets its own budget.
+          def replay(account_id:, limit: 100, after_id: 0, &on_change)
+            unless account_id.is_a?(String) && !account_id.empty? && limit.is_a?(Integer) && (1..1000).cover?(limit) &&
+                after_id.is_a?(Integer) && after_id >= 0
+              raise ArgumentError, "An account, limit of 1..1000 and nonnegative cursor are required"
+            end
+            scope = RoutingDeliveryReceipt.where(account_id: account_id, state: "pending").where("id > ?", after_id).order(:id)
+            rows = scope.limit(limit).to_a
+            errors = []
+            rows.each do |receipt|
+              apply(receipt, &on_change)
+            rescue StandardError => error
+              errors << {receipt_id: receipt.id, error: error}
+            end
+            cursor = rows.last&.id || after_id
+            ReplayResult.new(after_id: cursor, processed: rows.length, errors: errors,
+              finished: !RoutingDeliveryReceipt.where(account_id: account_id, state: "pending").where("id > ?", cursor).exists?)
+          end
+
+          private
+
+          def validate!(delivery, evidence)
+            ids = OutboundDelivery.where(account_id: evidence.account_id,
+              provider_message_id: [evidence.message_id, "<#{evidence.message_id}>"]).limit(2).pluck(:id)
+            unless delivery.state == "accepted" && delivery.account_id == evidence.account_id && ids == [delivery.id] &&
+                MessageId.normalize(delivery.provider_message_id) == evidence.message_id &&
+                delivery.from_address.casecmp?(evidence.event.fetch("from")) && delivery.request_started_at &&
+                evidence.occurred_at >= Time.at(delivery.request_started_at.to_i).utc
+              raise InvalidEvidence, "Routing analytics requires one matching accepted outbound operation"
+            end
+            recipients = delivery.outbound_recipients.to_a
+            envelope = delivery.recipients
+            unless envelope.is_a?(Array) && envelope.one? && recipients.one? &&
+                recipients.first.recipient == Outbox.normalize_recipient(envelope.first) &&
+                recipients.first.acceptance_state == "accepted"
+              raise InvalidEvidence, "Routing analytics requires one accepted saved envelope recipient"
+            end
+            recipients.first
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/email/check_route_task.rb

@@ -0,0 +1,21 @@
+require "cloudflare/email/credentials"
+require "cloudflare/email/routing_diagnostics"
+require "cloudflare/email/worker_deployer"
+
+module Cloudflare
+  module Email
+    class CheckRouteTask
+      def self.call(address:, worker_name: nil, account_id: nil, io: $stdout)
+        report = RoutingDiagnostics.new(api_token: Credentials.management_token).check(
+          address: address, worker_name: worker_name || WorkerDeployer.default_script_name,
+          account_id: account_id || Credentials.account_id)
+        report[:checks].each { |check| io.puts "#{check[:status].upcase} #{check[:name]}: #{check[:message]}" }
+        io.puts report[:limitations]
+        report[:status] == "pass" ? 0 : 1
+      rescue StandardError
+        io.puts "UNKNOWN: Unable to inspect routing. Check ADDRESS, WORKER_NAME, and Cloudflare management credentials."
+        1
+      end
+    end
+  end
+end

data/lib/cloudflare/email/client.rb

@@ -2,6 +2,8 @@ require "net/http"
 require "json"
 require "uri"
 require "time"
+require "timeout"
+require "zlib"
 require "cloudflare/email/endpoint"
 
 module Cloudflare
@@ -11,33 +13,47 @@ module Cloudflare
       DEFAULT_RETRIES  = 3
       DEFAULT_TIMEOUT  = 30
       DEFAULT_BACKOFF  = 0.5
+      DEFAULT_MAX_RESPONSE_BYTES = 1_048_576
       MAX_RETRY_AFTER  = 60 # seconds; never sleep longer than this even if server says so
 
       RETRYABLE_NETWORK = [
         Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Errno::ECONNRESET,
         Errno::ECONNREFUSED, Errno::EHOSTUNREACH, EOFError, SocketError,
-        IOError
+        IOError, Timeout::Error, Net::HTTPBadResponse, Net::HTTPHeaderSyntaxError,
+        OpenSSL::SSL::SSLError, Zlib::Error
       ].freeze
       PRE_SEND_NETWORK = [Net::OpenTimeout, Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError].freeze
 
-      attr_reader :account_id, :base_url, :retries, :timeout, :retry_ambiguous
+      attr_reader :account_id, :base_url, :retries, :timeout, :retry_ambiguous,
+                  :total_timeout, :max_response_bytes
 
       def initialize(account_id:, api_token:, base_url: DEFAULT_BASE_URL,
                      retries: DEFAULT_RETRIES, timeout: DEFAULT_TIMEOUT,
                      initial_backoff: DEFAULT_BACKOFF, max_retry_after: MAX_RETRY_AFTER,
-                     retry_ambiguous: false, logger: nil)
+                     retry_ambiguous: false, logger: nil,
+                     total_timeout: timeout, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES)
         unless account_id.is_a?(String) && account_id.match?(/\A[a-zA-Z0-9_-]+\z/)
           raise ConfigurationError, "account_id is required and must be a single account identifier"
         end
         unless api_token.is_a?(String) && !api_token.empty? && !api_token.match?(/\s/)
           raise ConfigurationError, "api_token is required and must not contain whitespace"
         end
+        [[:timeout, timeout], [:total_timeout, total_timeout]].each do |name, value|
+          unless value.is_a?(Numeric) && value.real? && value.finite? && value.positive?
+            raise ConfigurationError, "#{name} must be a finite positive number"
+          end
+        end
+        unless max_response_bytes.is_a?(Integer) && max_response_bytes.positive?
+          raise ConfigurationError, "max_response_bytes must be a positive integer"
+        end
 
         @account_id      = account_id
         @api_token       = api_token
         @base_url        = Endpoint.parse(base_url).to_s.delete_suffix("/")
         @retries         = retries
         @timeout         = timeout
+        @total_timeout   = total_timeout
+        @max_response_bytes = max_response_bytes
         @initial_backoff = initial_backoff
         @max_retry_after = max_retry_after
         @logger          = logger
@@ -143,9 +159,9 @@ module Cloudflare
           do_request(method, uri, body)
         rescue *RETRYABLE_NETWORK => e
           unless PRE_SEND_NETWORK.any? { |type| e.is_a?(type) } || @retry_ambiguous
-            raise NetworkError.new("#{e.message}; delivery outcome is unknown; automatic retry disabled")
+            raise NetworkError.new("provider response could not be read; delivery outcome is unknown; automatic retry disabled"), cause: nil
           end
-          raise NetworkError.new(e.message) if attempts > @retries
+          raise NetworkError.new("provider request could not be completed; request outcome is unknown"), cause: nil if attempts > @retries
           log_retry(attempts, e)
           sleep(backoff); backoff *= 2
           retry
@@ -194,13 +210,32 @@ module Cloudflare
         req["User-Agent"]    = "cloudflare-email-ruby/#{Cloudflare::Email::VERSION}"
         req.body = JSON.generate(body) if body
 
-        response = http.request(req)
-        handle_response(response)
+        raw = +"".b
+        response = nil
+        byte_limit = response_byte_limit(uri)
+        # Bound each network attempt, including trickling headers/body. Parsing,
+        # queue handlers, and database transactions are outside this deadline.
+        Timeout.timeout(@total_timeout) do
+          http.request(req) do |incoming|
+            response = incoming
+            incoming.read_body do |chunk|
+              # Net::HTTP yields decompressed bytes, so compressed expansion is
+              # subject to the same budget. Check before extending the buffer.
+              raise IOError, "provider response exceeds byte limit" if raw.bytesize + chunk.bytesize > byte_limit
+              raw << chunk
+            end
+          end
+        end
+        handle_response(response, raw)
+      end
+
+      def response_byte_limit(_uri)
+        @max_response_bytes
       end
 
-      def handle_response(response)
+      def handle_response(response, raw = response.body)
         status  = response.code.to_i
-        body    = parse_body(response.body)
+        body    = parse_body(raw)
         retry_after = response["Retry-After"]
 
         # Stash Retry-After on the error response so retry logic can use it.
@@ -236,7 +271,7 @@ module Cloudflare
         return {} if raw.nil? || raw.empty?
         JSON.parse(raw)
       rescue JSON::ParserError
-        { "errors" => [{ "message" => raw.to_s[0, 200] }] }
+        { "errors" => [{ "message" => "invalid JSON API response; request outcome is unknown" }] }
       end
 
       def extract_message(body)

data/lib/cloudflare/email/delivery_method.rb

@@ -25,6 +25,8 @@ module Cloudflare
           base_url:    settings[:base_url] || Cloudflare::Email::Client::DEFAULT_BASE_URL,
           retries:     settings.fetch(:retries,  Cloudflare::Email::Client::DEFAULT_RETRIES),
           timeout:     settings.fetch(:timeout,  Cloudflare::Email::Client::DEFAULT_TIMEOUT),
+          total_timeout: settings.fetch(:total_timeout, settings.fetch(:timeout, Cloudflare::Email::Client::DEFAULT_TIMEOUT)),
+          max_response_bytes: settings.fetch(:max_response_bytes, Cloudflare::Email::Client::DEFAULT_MAX_RESPONSE_BYTES),
           initial_backoff: settings.fetch(:initial_backoff, Cloudflare::Email::Client::DEFAULT_BACKOFF),
           max_retry_after: settings.fetch(:max_retry_after, Cloudflare::Email::Client::MAX_RETRY_AFTER),
           retry_ambiguous: settings.fetch(:retry_ambiguous, false),

data/lib/cloudflare/email/deploy_worker_task.rb

@@ -6,8 +6,8 @@ module Cloudflare
     # `bin/rails cloudflare:email:deploy_worker` — uploads the Worker
     # script + both secrets via the Cloudflare API. No wrangler required.
     class DeployWorkerTask < TaskBase
-      def self.call(script_path: nil, ingress_url: nil, io: $stdout)
-        new(io: io, script_path: script_path, ingress_url: ingress_url).call
+      def self.call(script_path: nil, ingress_url: nil, delivery_mode: "durable", io: $stdout)
+        new(io: io, script_path: script_path, ingress_url: ingress_url, delivery_mode: delivery_mode).call
       end
 
       protected
@@ -28,7 +28,7 @@ module Cloudflare
         )
 
         say "  Deploying Worker '#{deployer.script_name}'..."
-        deployer.deploy(script_path: path)
+        deployer.deploy(script_path: path, delivery_mode: opts[:delivery_mode])
         say "  ✓ Worker script deployed"
 
         deployer.put_secret("INGRESS_SECRET", ingress_secret)

data/lib/cloudflare/email/engine.rb

@@ -1,4 +1,5 @@
 require "rails/engine"
+require "mailbox_kit/railtie"
 require "cloudflare/email/dev_ingress_guard"
 
 # Register the delivery method at engine load time (not inside an initializer)
@@ -18,20 +19,12 @@ module Cloudflare
         app.middleware.insert_before 0, DevIngressGuard if Rails.env.development?
       end
 
-      config.to_prepare do
-        if (defined?(Cloudflare::Email::Tenancy) && Cloudflare::Email::Tenancy.enabled?) ||
-            (defined?(Cloudflare::Email::Mailboxes) && Cloudflare::Email::Mailboxes.enabled?)
-          require "cloudflare/email/tenant_job_context"
-          Cloudflare::Email::TenantJobContext.install_framework_jobs!
-        end
-        if defined?(Cloudflare::Email::Mailboxes) && Cloudflare::Email::Mailboxes.enabled? && defined?(::ActionMailbox::Engine)
-          require "cloudflare/email/mailboxes/inbound_retention"
-          ::ActionMailbox::InboundEmail.prepend(Cloudflare::Email::Mailboxes::InboundRetention) unless
-            ::ActionMailbox::InboundEmail.ancestors.include?(Cloudflare::Email::Mailboxes::InboundRetention)
-        end
-      end
-
       config.before_initialize do
+        unless defined?(Cloudflare::Email::Management::Engine)
+          Rails.autoloaders.main.ignore(
+            File.expand_path("../../../app/controllers/cloudflare/email/management", __dir__),
+          )
+        end
         unless defined?(::ActionMailbox::Engine)
           Rails.autoloaders.main.ignore(
             File.expand_path("../../../app/controllers/cloudflare/email/ingress_controller.rb", __dir__),

data/lib/cloudflare/email/envelope.rb

@@ -1,3 +1,4 @@
+require "mailbox_kit/address_syntax"
 require "json"
 require "cloudflare/email/signing"
 
@@ -8,19 +9,8 @@ module Cloudflare
     module Envelope
       METADATA_KEY = "cloudflare_email_envelope".freeze
       MAX_ENCODED_BYTES = 1024
-      LOCAL_PART = /\A[A-Za-z0-9.!#$%&'*+\/=\?^_`{|}~-]+\z/
-      DOMAIN_LABEL = /\A[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?\z/
-
       def self.valid_address?(address, allow_empty: false)
-        return false unless address.is_a?(String) && address.ascii_only?
-        return true if allow_empty && address.empty?
-        return false if address.bytesize > 254
-        parts = address.split("@", -1)
-        return false unless parts.size == 2
-        local, domain = parts
-        local.bytesize <= 64 && LOCAL_PART.match?(local) &&
-          !local.start_with?(".") && !local.end_with?(".") && !local.include?("..") &&
-          domain.split(".", -1).all? { |label| DOMAIN_LABEL.match?(label) }
+        MailboxKit::AddressSyntax.valid_address?(address, allow_empty: allow_empty)
       end
 
       def self.valid?(value)
@@ -45,11 +35,11 @@ module Cloudflare
         nil
       end
 
-      # Only metadata written after v2 verification is trusted. MIME headers
+      # Only metadata written after v2/v3 verification is trusted. MIME headers
       # (including X-CF-* headers) never participate in this lookup.
       def self.for(inbound_email)
         metadata = inbound_email.raw_email.blob&.metadata&.fetch(METADATA_KEY, nil)
-        return nil unless metadata.is_a?(Hash) && metadata["version"] == 2
+        return nil unless metadata.is_a?(Hash) && [2, 3].include?(metadata["version"])
         value = metadata.reject { |key, _| key == "version" }
         valid?(value) ? value : nil
       end

data/lib/cloudflare/email/error.rb

@@ -1,18 +1,11 @@
+require "mailbox_kit/error"
+
 module Cloudflare
   module Email
-    class Error < StandardError
-      attr_reader :response, :status
-
-      def initialize(message = nil, status: nil, response: nil)
-        super(message)
-        @status   = status
-        @response = response
-      end
-    end
-
-    class ConfigurationError < Error; end
+    Error = MailboxKit::Error
+    ConfigurationError = MailboxKit::ConfigurationError
     class AuthenticationError < Error; end
-    class ValidationError < Error; end
+    ValidationError = MailboxKit::ValidationError
     class RateLimitError < Error; end
     class ServerError < Error; end
     class NetworkError < Error; end

data/lib/cloudflare/email/event_consumer.rb

@@ -9,9 +9,12 @@ module Cloudflare
     # Handler/parse/ack failures propagate; unacknowledged leases expire and
     # are redelivered according to the queue's retry/dead-letter policy.
     class EventConsumer < Client
-      def initialize(queue_id:, domains: nil, **options)
+      # Up to 100 queue messages, including encoded payloads and metadata.
+      DEFAULT_MAX_RESPONSE_BYTES = 32 * 1_048_576
+
+      def initialize(queue_id:, domains: nil, max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES, **options)
         raise ConfigurationError, "queue_id is required" unless queue_id.to_s.match?(/\A[a-zA-Z0-9_-]+\z/)
-        super(**options.merge(retries: 0, retry_ambiguous: false))
+        super(**options.merge(retries: 0, retry_ambiguous: false, max_response_bytes: max_response_bytes))
         @queue_id = queue_id
         @domains = domains && Array(domains).map(&:downcase)
       end
@@ -53,6 +56,12 @@ module Cloudflare
 
       private
 
+      def response_byte_limit(uri)
+        # ACKs contain counts, never a queue batch. Keep their smaller budget
+        # even when a pull needs room for 100 encoded event payloads.
+        uri.path.end_with?("/messages/ack") ? [@max_response_bytes, Client::DEFAULT_MAX_RESPONSE_BYTES].min : @max_response_bytes
+      end
+
       def queue_path(action)
         "/accounts/#{account_id}/queues/#{@queue_id}/messages/#{action}"
       end
@@ -79,7 +88,7 @@ module Cloudflare
         end
         DeliveryEvent.new(body)
       rescue JSON::ParserError, ArgumentError, TypeError
-        raise ValidationError, "queue body must contain a valid JSON Email Sending event"
+        raise ValidationError, "queue body must contain a valid JSON Email Sending event", cause: nil
       end
     end
   end

data/lib/cloudflare/email/ingress.rb

@@ -0,0 +1,126 @@
+require "digest"
+require "cloudflare/email/verification"
+
+module Cloudflare
+  module Email
+    # Shared bounded verification for custom Rack/Rails ingestion endpoints.
+    # This API deliberately performs no domain lookup or business processing.
+    module Ingress
+      DEFAULT_MAX_EMAIL_BYTES = 25 * 1024 * 1024
+      Result = Struct.new(:status, :message, :bytes, keyword_init: true)
+
+      class VerifiedMessage
+        attr_reader :body, :envelope, :provider_metadata, :storage_metadata, :message_checksum
+
+        def initialize(body:, envelope:, provider_metadata:, version:)
+          @body = body.b.freeze
+          @envelope = Ingress.deep_freeze(envelope)
+          @provider_metadata = Ingress.deep_freeze(provider_metadata)
+          @storage_metadata = {Envelope::METADATA_KEY => envelope.merge("version" => version.to_i)}
+          if provider_metadata
+            @storage_metadata[ProviderMetadata::METADATA_KEY] = provider_metadata.merge("signature_version" => 3)
+          end
+          Ingress.deep_freeze(@storage_metadata)
+          identity = if version == "3"
+            "v3\0#{JSON.generate([envelope.fetch('from'), envelope.fetch('to'), ProviderMetadata.canonical(provider_metadata)])}\0".b
+          else
+            "v2\0#{envelope.fetch('to')}\0".b
+          end
+          @message_checksum = Digest::SHA256.hexdigest(identity + @body).freeze
+          freeze
+        end
+        private_class_method :new
+
+        # Call within Mailboxes.receive when using the optional registry so the
+        # framework records and memberships share the resolved tenant context.
+        # Custom endpoints may instead persist body/metadata in their own store.
+        def persist_action_mailbox!
+          result = persist_rails_record
+          result.record if result.created?
+        end
+
+        # Verify once, resolve the envelope recipient before storage, then use
+        # the kit's ordinary Rails membership path. A duplicate can repair a
+        # missing membership without scheduling Rails processing again.
+        def receive_into_mailbox!
+          result = nil
+          Mailboxes.receive(recipient: envelope.fetch("to")) do
+            result = persist_rails_record
+            result.record
+          end
+          result.record if result.created?
+        end
+
+        private
+
+        def persist_rails_record
+          require "mailbox_kit/inbound_email"
+          MailboxKit::InboundEmail.persist(source: body, message_checksum: message_checksum,
+            message_id: stable_message_id, metadata: storage_metadata)
+        end
+
+        # ActionMailbox's fallback includes Socket.gethostname. A replay on a
+        # different Rails host must use the same database identity, while the
+        # original MIME stays untouched. Preserve parseable provider IDs.
+        def stable_message_id
+          parsed = begin
+            ::Mail.from_source(body).message_id
+          rescue StandardError
+            nil
+          end
+          parsed || "#{message_checksum}@cloudflare-email.invalid"
+        end
+      end
+
+      def self.verify(secret:, headers:, body:, content_length: nil,
+        max_email_bytes: DEFAULT_MAX_EMAIL_BYTES, now: Time.now.to_i, window: Verification::DEFAULT_WINDOW)
+        unless max_email_bytes.is_a?(Integer) && max_email_bytes.positive?
+          raise ArgumentError, "max_email_bytes must be a positive integer"
+        end
+        values = %w[Timestamp Signature Signature-Version Envelope Metadata].to_h do |name|
+          key = "X-CF-Email-#{name}"
+          value = headers[key] || headers["HTTP_#{key.upcase.tr('-', '_')}"]
+          [name, value.is_a?(String) ? value.dup.freeze : value]
+        end
+        options = {secret: secret, timestamp: values["Timestamp"], signature: values["Signature"],
+          version: values["Signature-Version"], envelope: values["Envelope"], metadata: values["Metadata"],
+          now: now, window: window}
+        status = Verification.verify_headers(**options)
+        return Result.new(status: status).freeze unless status == :ok
+        if content_length
+          length = Integer(content_length.to_s, exception: false)
+          return Result.new(status: :bad_signature).freeze unless length && length >= 0
+          return Result.new(status: :too_large).freeze if length > max_email_bytes
+        end
+        raw = if body.is_a?(String)
+          return Result.new(status: :too_large).freeze if body.bytesize > max_email_bytes
+          body.dup.b
+        elsif body.respond_to?(:read)
+          buffer = +"".b
+          while buffer.bytesize <= max_email_bytes
+            chunk = body.read(max_email_bytes + 1 - buffer.bytesize)
+            break if chunk.nil? || chunk.empty?
+            buffer << chunk.b
+          end
+          buffer
+        else
+          raise ArgumentError, "body must be a String or readable IO"
+        end
+        return Result.new(status: :too_large).freeze if raw.bytesize > max_email_bytes
+        status = Verification.verify(body: raw, **options)
+        return Result.new(status: status, bytes: raw.bytesize).freeze unless status == :ok
+        message = VerifiedMessage.send(:new, body: raw, version: values["Signature-Version"],
+          envelope: Envelope.decode(values["Envelope"]), provider_metadata: ProviderMetadata.decode(values["Metadata"]))
+        Result.new(status: :ok, message: message, bytes: raw.bytesize).freeze
+      end
+
+      def self.deep_freeze(value)
+        case value
+        when Hash then value.each { |key, item| deep_freeze(key); deep_freeze(item) }
+        when Array then value.each { |item| deep_freeze(item) }
+        end
+        value.freeze
+      end
+    end
+  end
+end

data/lib/cloudflare/email/mailboxes/configuration.rb

@@ -1,28 +1,23 @@
-require "active_record"
+require "mailbox_kit/mailboxes/configuration"
 require "cloudflare/email/error"
 
 module Cloudflare
   module Email
+    Mailboxes = MailboxKit::Mailboxes unless const_defined?(:Mailboxes, false)
     module Mailboxes
-      class Unavailable < Cloudflare::Email::Error; end
 
-      class << self
+      module CloudflareConfiguration
         def configure(directory_base: ::ActiveRecord::Base, client_resolver: nil)
-          if const_defined?(:ReceivingDomain, false)
-            raise ConfigurationError, "configure mailboxes before loading mailbox models"
-          end
-          unless directory_base.is_a?(Class) && directory_base <= ::ActiveRecord::Base
-            raise ConfigurationError, "directory_base must be an ActiveRecord base class"
-          end
           if client_resolver && !client_resolver.respond_to?(:call)
             raise ConfigurationError, "client_resolver must be callable"
           end
-          @directory_base = directory_base
+          super(directory_base: directory_base)
           @client_resolver = client_resolver
         end
+      end
+      singleton_class.prepend(CloudflareConfiguration)
 
-        def directory_base = @directory_base || ::ActiveRecord::Base
-
+      class << self
         def delivery_handler = rails_setting(:outbox_delivery_handler)
         def recipient_handler = rails_setting(:outbox_recipient_handler)
 
@@ -42,9 +37,6 @@ module Cloudflare
           client
         end
 
-        def enabled? = @enabled == true
-        def enable! = @enabled = true
-
         private
 
         def rails_setting(name)

data/lib/cloudflare/email/mailboxes/inbound_retention.rb

@@ -1,14 +1 @@
-module Cloudflare
-  module Email
-    module Mailboxes
-      # ActionMailbox normally deletes processed mail after its retention window.
-      # A mailbox membership owns the raw source until explicit application purge.
-      module InboundRetention
-        def incinerate
-          return if Mailboxes.enabled? && Message.where(inbound_email_id: id).exists?
-          super
-        end
-      end
-    end
-  end
-end
+require "mailbox_kit/mailboxes/inbound_retention"