cloudflare-email 0.1.0 → 0.3.0

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

@@ -0,0 +1,22 @@
+require "cloudflare/email/active_record/base"
+
+module Cloudflare
+  module Email
+    module ActiveRecord
+      class OutboundDelivery < Base
+        self.table_name = "cloudflare_email_outbound_deliveries"
+        has_many :outbound_recipients, class_name: "Cloudflare::Email::ActiveRecord::OutboundRecipient", dependent: :restrict_with_exception
+        has_many :outbound_reconciliations, class_name: "Cloudflare::Email::ActiveRecord::OutboundReconciliation", dependent: :restrict_with_exception
+        attr_readonly :account_id, :operation_key, :from_address, :recipients_json, :mime_message, :snapshot_digest
+
+        def recipients
+          JSON.parse(recipients_json)
+        end
+
+        def response
+          Response.new(JSON.parse(response_json)) if response_json
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+require "cloudflare/email/active_record/base"
+
+module Cloudflare
+  module Email
+    module ActiveRecord
+      class OutboundRecipient < Base
+        self.table_name = "cloudflare_email_outbound_recipients"
+        belongs_to :outbound_delivery, class_name: "Cloudflare::Email::ActiveRecord::OutboundDelivery"
+        attr_readonly :outbound_delivery_id, :recipient
+      end
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+require "cloudflare/email/active_record/base"
+
+module Cloudflare
+  module Email
+    module ActiveRecord
+      class OutboundReconciliation < Base
+        self.table_name = "cloudflare_email_outbound_reconciliations"
+        belongs_to :outbound_delivery, class_name: "Cloudflare::Email::ActiveRecord::OutboundDelivery"
+        def readonly?
+          persisted?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,219 @@
+require "active_record"
+require "digest"
+require "cloudflare-email"
+require "cloudflare/email/active_record/outbound_delivery"
+require "cloudflare/email/active_record/outbound_recipient"
+require "cloudflare/email/active_record/outbound_reconciliation"
+
+module Cloudflare
+  module Email
+    module ActiveRecord
+      # Durable, single-attempt boundary. A retry job may revisit an accepted
+      # operation, but uncertainty always requires an explicit operator decision.
+      class Outbox
+        class Error < Cloudflare::Email::Error; end
+        class InvalidTransition < Error; end
+        class SnapshotConflict < Error; end
+
+        class << self
+          def acceptance_state(states)
+            aggregate(states)
+          end
+
+          def normalize_recipient(value)
+            local, separator, domain = value.to_s.rpartition("@")
+            separator.empty? ? value.to_s : "#{local}@#{domain.downcase}"
+          end
+
+          def prepare(account_id:, operation_key:, from:, recipients:, mime_message:)
+            [account_id, operation_key, from].each do |value|
+              raise ArgumentError, "account, operation key and sender must be nonempty strings" unless value.is_a?(String) && !value.strip.empty?
+            end
+            unless recipients.is_a?(Array) && recipients.any? && recipients.all? { |v| v.is_a?(String) && !v.strip.empty? }
+              raise ArgumentError, "recipients must be a nonempty array of addresses"
+            end
+            raise ArgumentError, "mime_message must be a nonempty String" unless mime_message.is_a?(String) && !mime_message.empty?
+            addresses = recipients.map { |address| normalize_recipient(address) }.uniq
+            json = JSON.generate(addresses)
+            digest = Digest::SHA256.hexdigest(JSON.generate([account_id, from, addresses]) + "\0" + mime_message.b)
+            OutboundDelivery.transaction do
+              delivery = OutboundDelivery.create_or_find_by!(account_id: account_id, operation_key: operation_key) do |row|
+                row.assign_attributes(from_address: from, recipients_json: json, mime_message: mime_message.b,
+                  snapshot_digest: digest, state: "prepared")
+              end
+              raise SnapshotConflict, "operation key already has a different immutable message" unless delivery.snapshot_digest == digest
+              addresses.each { |address| delivery.outbound_recipients.create_or_find_by!(recipient: address) }
+              delivery
+            end
+          end
+
+          def deliver(delivery, client: nil)
+            persisted!(delivery)
+            outside_transaction!
+            delivery.reload
+            return delivery if %w[accepted partial].include?(delivery.state)
+            client ||= Client.new(account_id: Credentials.account_id, api_token: Credentials.api_token)
+            unless client.account_id.to_s == delivery.account_id && client.respond_to?(:retry_ambiguous) && client.retry_ambiguous == false
+              raise ConfigurationError, "outbox client must match the account and disable ambiguous retries"
+            end
+            now = Time.now.utc
+            claimed = OutboundDelivery.where(id: delivery.id, state: "prepared").update_all(state: "sending", request_started_at: now, updated_at: now)
+            unless claimed == 1
+              delivery.reload
+              return delivery if %w[accepted partial].include?(delivery.state)
+              raise InvalidTransition, "cannot send an operation in #{delivery.state}; uncertainty requires reconciliation"
+            end
+
+            # Everything after this durable claim can leave an ambiguous outcome.
+            begin
+              response = client.send_raw(from: delivery.from_address, recipients: delivery.recipients, mime_message: delivery.mime_message)
+            rescue StandardError => error
+              record_failure(delivery, error)
+              raise
+            end
+            begin
+              outcomes, provider_message_id = response_outcomes(response, delivery.recipients)
+              delivery.with_lock do
+                raise InvalidTransition, "send claim changed during delivery" unless delivery.state == "sending"
+                outcomes.each do |address, state|
+                  delivery.outbound_recipients.find_by!(recipient: address).update!(state: state, acceptance_state: state, occurred_at: nil,
+                    terminal: %w[delivered bounced suppressed].include?(state))
+                end
+                delivery.update!(state: aggregate(outcomes.values), provider_message_id: provider_message_id,
+                  response_json: JSON.generate(response.to_h), completed_at: Time.now.utc, error_class: nil)
+              end
+            rescue StandardError => error
+              # Even a local validation/persistence error here follows provider
+              # acceptance. Never convert it into permission to resend.
+              mark_unknown(delivery.id, error)
+              raise
+            end
+            delivery.reload
+          end
+
+          def reconcile(delivery, outcome:, actor:, reason:, evidence:, provider_message_id: nil, recipients: nil, confirm_sender_stopped: false)
+            persisted!(delivery)
+            raise ArgumentError, "outcome must be accepted or not_sent" unless %w[accepted not_sent].include?(outcome.to_s)
+            [actor, reason, evidence].each do |value|
+              raise ArgumentError, "actor, reason and evidence are required strings" unless value.is_a?(String) && !value.strip.empty?
+            end
+            provider_message_id = validated_message_id(provider_message_id)
+            if outcome.to_s == "accepted" && provider_message_id.nil?
+              raise ArgumentError, "accepted reconciliation requires a provider message ID"
+            end
+            completed = false
+            delivery.with_lock(requires_new: true) do
+              allowed = %w[unknown partial].include?(delivery.state) || (delivery.state == "sending" && confirm_sender_stopped == true &&
+                delivery.request_started_at && delivery.request_started_at <= Time.now.utc - 900)
+              raise InvalidTransition, "only uncertain operations may be reconciled; a sending process must be confirmed stopped and at least 15 minutes old" unless allowed
+              rows = delivery.outbound_recipients.to_a
+              unresolved = rows.select { |row| %w[unknown prepared sending].include?(row.acceptance_state) }.map(&:recipient)
+              selected = recipients || unresolved
+              selected = selected.map { |address| normalize_recipient(address) } if selected.is_a?(Array)
+              unless selected.is_a?(Array) && selected.any? && (selected - unresolved).empty? && selected.uniq == selected
+                raise ArgumentError, "recipients must be unique unresolved snapshot recipients"
+              end
+              existing_id = validated_message_id(delivery.provider_message_id.presence)
+              if provider_message_id && existing_id && provider_message_id != existing_id
+                raise ArgumentError, "provider message ID conflicts with the existing operation"
+              end
+              delivery.outbound_reconciliations.create!(actor: actor, reason: reason, evidence: evidence,
+                outcome: outcome.to_s, provider_message_id: provider_message_id, recipients_json: JSON.generate(selected))
+              states = rows.map do |recipient|
+                unless selected.include?(recipient.recipient)
+                  recipient.update!(state: "unknown", acceptance_state: "unknown") if %w[prepared sending].include?(recipient.acceptance_state)
+                  next recipient.acceptance_state
+                end
+                state = outcome.to_s == "not_sent" ? "not_sent" : "accepted"
+                recipient.update!(state: state, acceptance_state: state, occurred_at: nil, terminal: state == "not_sent")
+                state
+              end
+              delivery.update!(state: states.all? { |state| state == "not_sent" } ? "confirmed_not_sent" : aggregate(states),
+                provider_message_id: provider_message_id || existing_id, completed_at: Time.now.utc)
+              yield delivery if block_given?
+              completed = true
+            end
+            raise InvalidTransition, "reconciliation rolled back instead of completing" unless completed
+            delivery.reload
+          end
+
+          private
+
+          def persisted!(delivery)
+            raise ArgumentError, "expected a persisted OutboundDelivery" unless delivery.is_a?(OutboundDelivery) && delivery.persisted?
+          end
+
+          def outside_transaction!
+            raise ArgumentError, "outbox network delivery must run outside an existing database transaction" if OutboundDelivery.connection.transaction_open?
+          end
+
+          def record_failure(delivery, error)
+            # Only an explicit provider 4xx rejection proves nonacceptance.
+            rejected = error.is_a?(Cloudflare::Email::Error) && [400, 401, 403, 422, 429].include?(error.status)
+            OutboundDelivery.transaction do
+              count = OutboundDelivery.where(id: delivery.id, state: "sending").update_all(state: rejected ? "rejected" : "unknown",
+                error_class: error.class.name, completed_at: Time.now.utc, updated_at: Time.now.utc)
+              OutboundRecipient.where(outbound_delivery_id: delivery.id).update_all(state: rejected ? "rejected" : "unknown", acceptance_state: rejected ? "rejected" : "unknown") if count == 1
+            end
+          rescue StandardError
+            # A database outage leaves the already committed sending claim.
+            # It is deliberately just as non-retryable as unknown.
+            nil
+          end
+
+          def mark_unknown(id, error)
+            OutboundDelivery.where(id: id, state: "sending").update_all(state: "unknown", error_class: error.class.name, updated_at: Time.now.utc)
+          rescue StandardError
+            nil
+          end
+
+          def response_outcomes(response, addresses)
+            raise ValidationError, "invalid provider response" unless response.is_a?(Response) && response.success?
+            outcomes = addresses.to_h { |address| [address, "unknown"] }
+            result = response.result
+            ids = [validated_message_id(result["message_id"])]
+            groups = { "delivered" => "delivered", "queued" => "queued", "permanent_bounces" => "bounced", "suppressed_recipients" => "suppressed" }
+            seen = {}
+            groups.each do |key, state|
+              entries = result.fetch(key, [])
+              raise ValidationError, "invalid recipient outcomes" unless entries.is_a?(Array)
+              entries.each do |entry|
+                ids << validated_message_id(entry["message_id"]) if entry.is_a?(Hash)
+                address = entry.is_a?(Hash) ? (entry["to"] || entry["email"] || entry["recipient"] || entry["address"]) : entry
+                address = normalize_recipient(address)
+                raise ValidationError, "unknown or conflicting provider recipient" unless addresses.include?(address) && !seen[address]
+                seen[address] = true
+                outcomes[address] = state
+              end
+            end
+            raise ValidationError, "multiple provider message IDs cannot be correlated to one operation" if ids.compact.uniq.size > 1
+            if seen.empty? && ids.compact.any?
+              outcomes.transform_values! { "accepted" }
+            end
+            [outcomes, ids.compact.first]
+          end
+
+          def validated_message_id(value)
+            return nil if value.nil?
+            unless value.is_a?(String)
+              raise ValidationError, "provider message ID must be a nonempty string"
+            end
+            normalized = MessageId.normalize(value)
+            if normalized.empty? || normalized.match?(/[\s<>]/)
+              raise ValidationError, "provider message ID must not contain whitespace or brackets"
+            end
+            normalized
+          end
+
+          def aggregate(states)
+            accepted = states.count { |state| %w[accepted delivered queued].include?(state) }
+            return "accepted" if accepted == states.size
+            return "partial" if accepted.positive?
+            return "rejected" if states.all? { |state| %w[bounced suppressed rejected not_sent].include?(state) }
+            "unknown"
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,34 @@
+module Cloudflare
+  module Email
+    module ActiveRecord
+      module OutboxNotifications
+        def prepare(**options)
+          notify_outbox("prepare", account_id: options[:account_id], operation_key: options[:operation_key]) { super }
+        end
+
+        def deliver(delivery, **options)
+          notify_outbox("send", account_id: delivery.account_id, operation_key: delivery.operation_key) { super }
+        end
+
+        def reconcile(delivery, **options, &block)
+          notify_outbox("reconcile", account_id: delivery.account_id, operation_key: delivery.operation_key) { super }
+        end
+
+        private
+
+        def notify_outbox(action, **payload)
+          return yield unless defined?(::ActiveSupport::Notifications)
+
+          ::ActiveSupport::Notifications.instrument("cloudflare_email.outbox_#{action}", payload) do |details|
+            result = yield
+            details[:delivery_id] = result.id
+            details[:state] = result.state
+            result
+          end
+        end
+      end
+
+      Outbox.singleton_class.prepend(OutboxNotifications)
+    end
+  end
+end

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

@@ -0,0 +1,5 @@
+# Optional durable Rails/ActiveRecord integration. Jobs are a separate opt-in.
+require "cloudflare/email/active_record/outbox"
+require "cloudflare/email/active_record/mail_snapshot"
+require "cloudflare/email/active_record/delivery_events"
+require "cloudflare/email/active_record/outbox_notifications"

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