cloudflare-email 0.1.0

data/app/controllers/cloudflare/email/ingress_controller.rb

@@ -0,0 +1,67 @@
+require "cloudflare/email/verification"
+
+module Cloudflare
+  module Email
+    # ActionMailbox ingress for Cloudflare Email Worker forwards.
+    #
+    # The shipped Worker template signs each forwarded message with HMAC-SHA256
+    # over "{timestamp}.{raw_body}" and sends:
+    #   X-CF-Email-Timestamp: <unix seconds>
+    #   X-CF-Email-Signature: <hex digest>
+    #
+    # Set the shared secret in Rails credentials under cloudflare.ingress_secret
+    # (or in the CLOUDFLARE_INGRESS_SECRET env var) and as the Worker secret
+    # INGRESS_SECRET via `wrangler secret put INGRESS_SECRET`.
+    class IngressController < ActionMailbox::BaseController
+      param_encoding :create, "raw_email", Encoding::ASCII_8BIT
+
+      def create
+        ActiveSupport::Notifications.instrument(
+          "cloudflare_email.ingress",
+          bytes: raw_body.bytesize,
+        ) do |payload|
+          case Cloudflare::Email::Verification.verify(
+                secret:    secret,
+                body:      raw_body,
+                timestamp: request.headers["X-CF-Email-Timestamp"],
+                signature: request.headers["X-CF-Email-Signature"],
+              )
+          when :stale
+            payload[:result] = :stale
+            head :request_timeout
+          when :bad_signature
+            payload[:result] = :bad_signature
+            head :unauthorized
+          when :ok
+            inbound = ActionMailbox::InboundEmail.create_and_extract_message_id!(raw_body)
+            payload[:result]     = :ok
+            payload[:message_id] = inbound.message_id
+            head :ok
+          end
+        end
+      end
+
+      private
+
+      # Override ActionMailbox::BaseController's default name inference so
+      # `config.action_mailbox.ingress = :cloudflare` gates this controller.
+      def ingress_name
+        :cloudflare
+      end
+
+      def raw_body
+        @raw_body ||= begin
+          request.body.rewind if request.body.respond_to?(:rewind)
+          request.body.read
+        end
+      end
+
+      def secret
+        @secret ||= begin
+          require "cloudflare/email/credentials"
+          Cloudflare::Email::Credentials.ingress_secret
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/email/client.rb

@@ -0,0 +1,216 @@
+require "net/http"
+require "json"
+require "uri"
+
+module Cloudflare
+  module Email
+    class Client
+      DEFAULT_BASE_URL = "https://api.cloudflare.com/client/v4".freeze
+      DEFAULT_RETRIES  = 3
+      DEFAULT_TIMEOUT  = 30
+      DEFAULT_BACKOFF  = 0.5
+      MAX_RETRY_AFTER  = 60 # seconds; never sleep longer than this even if server says so
+
+      RETRYABLE_NETWORK = [
+        Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET,
+        Errno::ECONNREFUSED, Errno::EHOSTUNREACH, EOFError, SocketError,
+        IOError
+      ].freeze
+
+      attr_reader :account_id, :base_url, :retries, :timeout
+
+      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,
+                     logger: nil)
+        raise ConfigurationError, "account_id is required" if account_id.nil? || account_id.to_s.empty?
+        raise ConfigurationError, "api_token is required"  if api_token.nil?  || api_token.to_s.empty?
+
+        @account_id      = account_id
+        @api_token       = api_token
+        @base_url        = base_url
+        @retries         = retries
+        @timeout         = timeout
+        @initial_backoff = initial_backoff
+        @max_retry_after = max_retry_after
+        @logger          = logger
+      end
+
+      def send(from:, to:, subject:, text: nil, html: nil, cc: nil, bcc: nil,
+               reply_to: nil, headers: nil, attachments: nil)
+        raise ValidationError, "must provide :text or :html" if text.nil? && html.nil?
+
+        body = {
+          from:    normalize_address(from),
+          to:      wrap(to).map  { |addr| normalize_address(addr) },
+          subject: subject,
+        }
+        body[:text]        = text if text
+        body[:html]        = html if html
+        body[:cc]          = wrap(cc).map  { |a| normalize_address(a) } if cc
+        body[:bcc]         = wrap(bcc).map { |a| normalize_address(a) } if bcc
+        body[:reply_to]    = normalize_address(reply_to) if reply_to
+        body[:headers]     = headers if headers
+        body[:attachments] = attachments if attachments
+
+        perform(:send, "/accounts/#{@account_id}/email/sending/send", body)
+      end
+
+      def send_raw(from:, recipients:, mime_message:)
+        body = {
+          from:         extract_address(from),
+          recipients:   wrap(recipients).map { |r| extract_address(r) },
+          mime_message: mime_message,
+        }
+        perform(:send_raw, "/accounts/#{@account_id}/email/sending/send_raw", body)
+      end
+
+      private
+
+      # Wrap a value into an array without Hash-to-pair-array conversion.
+      def wrap(value)
+        case value
+        when Array then value
+        when nil   then []
+        else [value]
+        end
+      end
+
+      def normalize_address(addr)
+        case addr
+        when String
+          addr
+        when Hash
+          h = { address: addr[:address] || addr["address"] }
+          name = addr[:name] || addr["name"]
+          h[:name] = name if name
+          raise ValidationError, "address hash requires :address" unless h[:address]
+          h
+        else
+          raise ValidationError, "address must be a String or Hash, got #{addr.class}"
+        end
+      end
+
+      def extract_address(addr)
+        case addr
+        when String then addr
+        when Hash   then addr[:address] || addr["address"] || raise(ValidationError, "address hash requires :address")
+        else raise ValidationError, "address must be a String or Hash, got #{addr.class}"
+        end
+      end
+
+      def perform(operation, path, body)
+        instrument("cloudflare_email.#{operation}", account_id: @account_id, path: path) do |payload|
+          response = request(:post, path, body)
+          payload[:status]     = response.status
+          payload[:message_id] = response.message_id
+          response
+        end
+      end
+
+      def instrument(name, payload)
+        if defined?(ActiveSupport::Notifications)
+          ActiveSupport::Notifications.instrument(name, payload) { |p| yield p }
+        else
+          yield payload
+        end
+      end
+
+      def request(method, path, body)
+        uri = URI.parse("#{@base_url}#{path}")
+        attempts = 0
+        backoff  = @initial_backoff
+
+        begin
+          attempts += 1
+          do_request(method, uri, body)
+        rescue *RETRYABLE_NETWORK => e
+          raise NetworkError.new(e.message) if attempts > @retries
+          log_retry(attempts, e)
+          sleep(backoff); backoff *= 2
+          retry
+        rescue RateLimitError => e
+          raise if attempts > @retries
+          log_retry(attempts, e)
+          sleep(retry_after_from(e, backoff)); backoff *= 2
+          retry
+        rescue ServerError => e
+          raise if attempts > @retries
+          log_retry(attempts, e)
+          sleep(backoff); backoff *= 2
+          retry
+        end
+      end
+
+      def retry_after_from(error, fallback_backoff)
+        header = error.response.is_a?(Hash) ? error.response["retry_after"] : nil
+        value  = header || fallback_backoff
+        seconds = value.to_f
+        return fallback_backoff if seconds <= 0
+        [seconds, @max_retry_after].min
+      end
+
+      def do_request(method, uri, body)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl     = (uri.scheme == "https")
+        http.open_timeout = @timeout
+        http.read_timeout = @timeout
+
+        req_class = { post: Net::HTTP::Post, get: Net::HTTP::Get }.fetch(method)
+        req = req_class.new(uri.request_uri)
+        req["Authorization"] = "Bearer #{@api_token}"
+        req["Content-Type"]  = "application/json"
+        req["Accept"]        = "application/json"
+        req["User-Agent"]    = "cloudflare-email-ruby/#{Cloudflare::Email::VERSION}"
+        req.body = JSON.generate(body) if body
+
+        response = http.request(req)
+        handle_response(response)
+      end
+
+      def handle_response(response)
+        status  = response.code.to_i
+        body    = parse_body(response.body)
+        retry_after = response["Retry-After"]
+
+        # Stash Retry-After on the error response so retry logic can use it.
+        body = body.merge("retry_after" => retry_after) if body.is_a?(Hash) && retry_after
+
+        case status
+        when 200..299
+          Response.new(body, status: status)
+        when 400, 422
+          raise ValidationError.new(extract_message(body), status: status, response: body)
+        when 401, 403
+          raise AuthenticationError.new(extract_message(body), status: status, response: body)
+        when 429
+          raise RateLimitError.new(extract_message(body), status: status, response: body)
+        when 500..599
+          raise ServerError.new(extract_message(body), status: status, response: body)
+        else
+          raise Error.new("unexpected status #{status}: #{extract_message(body)}",
+                          status: status, response: body)
+        end
+      end
+
+      def parse_body(raw)
+        return {} if raw.nil? || raw.empty?
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        { "errors" => [{ "message" => raw.to_s[0, 200] }] }
+      end
+
+      def extract_message(body)
+        return "unknown error" unless body.is_a?(Hash)
+        errors = body["errors"]
+        return "unknown error" unless errors.is_a?(Array) && errors.any?
+        errors.map { |e| e.is_a?(Hash) ? e["message"] : e.to_s }.compact.join("; ")
+      end
+
+      def log_retry(attempt, error)
+        return unless @logger
+        @logger.warn("[cloudflare-email] retry #{attempt}: #{error.class}: #{error.message}")
+      end
+    end
+  end
+end

data/lib/cloudflare/email/credentials.rb

@@ -0,0 +1,59 @@
+module Cloudflare
+  module Email
+    # Unified credential lookup.
+    #
+    # Precedence:
+    #   1. Rails.application.credentials.dig(:cloudflare, key) — encrypted credentials.yml.enc
+    #      (respects per-environment files: config/credentials/{env}.yml.enc when present)
+    #   2. ENV["CLOUDFLARE_#{KEY}"] — env vars, including anything dotenv or foreman loaded from .env
+    #
+    # Supported keys:
+    #   account_id       — Cloudflare account ID
+    #   api_token        — runtime token used by the delivery method (needs Email Sending: Send)
+    #   management_token — higher-privilege token used by deploy/provision rake tasks
+    #                      (needs Workers Scripts: Edit, Zone: Read, Email Routing: Edit).
+    #                      Falls back to api_token if not set.
+    #   ingress_secret   — HMAC shared secret between Worker and Rails ingress
+    module Credentials
+      class << self
+        def account_id
+          fetch(:account_id)
+        end
+
+        def api_token
+          fetch(:api_token)
+        end
+
+        # For deploy_worker, provision_route, and dev tasks. Prefer a
+        # dedicated higher-privilege token if the user has split them;
+        # otherwise reuse api_token (most single-token setups).
+        def management_token
+          token = fetch(:management_token)
+          token.empty? ? api_token : token
+        end
+
+        def ingress_secret
+          fetch(:ingress_secret)
+        end
+
+        # True if the user has set a separate management token.
+        def split_tokens?
+          !fetch(:management_token).empty?
+        end
+
+        def fetch(key)
+          from_rails = rails_credentials_dig(key)
+          return from_rails unless from_rails.empty?
+          ENV["CLOUDFLARE_#{key.to_s.upcase}"].to_s
+        end
+
+        def rails_credentials_dig(key)
+          return "" unless defined?(Rails) && Rails.respond_to?(:application) && Rails.application
+          Rails.application.credentials.dig(:cloudflare, key).to_s
+        rescue StandardError
+          ""
+        end
+      end
+    end
+  end
+end

data/lib/cloudflare/email/delivery_method.rb

@@ -0,0 +1,57 @@
+require "cloudflare/email/client"
+
+module Cloudflare
+  module Email
+    # ActionMailer delivery method. Registered on the :cloudflare symbol by the Engine.
+    #
+    # Configure in your Rails app:
+    #
+    #   config.action_mailer.delivery_method   = :cloudflare
+    #   config.action_mailer.cloudflare_settings = {
+    #     account_id: Rails.application.credentials.dig(:cloudflare, :account_id),
+    #     api_token:  Rails.application.credentials.dig(:cloudflare, :api_token),
+    #   }
+    class DeliveryMethod
+      attr_accessor :settings
+
+      def initialize(settings = {})
+        @settings = settings
+      end
+
+      def deliver!(mail)
+        client = Cloudflare::Email::Client.new(
+          account_id:  settings.fetch(:account_id),
+          api_token:   settings.fetch(:api_token),
+          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),
+          logger:      settings[:logger],
+        )
+
+        from_addr  = mail.from && mail.from.first
+        recipients = collect_recipients(mail)
+
+        raise Cloudflare::Email::ValidationError, "mail has no :from address" if from_addr.nil?
+        raise Cloudflare::Email::ValidationError, "mail has no recipients" if recipients.empty?
+
+        response = client.send_raw(
+          from:         from_addr,
+          recipients:   recipients,
+          mime_message: mail.encoded,
+        )
+
+        if response.message_id && mail.respond_to?(:message_id=)
+          mail.message_id = response.message_id
+        end
+
+        response
+      end
+
+      private
+
+      def collect_recipients(mail)
+        [mail.to, mail.cc, mail.bcc].compact.flatten.uniq
+      end
+    end
+  end
+end

data/lib/cloudflare/email/deploy_worker_task.rb

@@ -0,0 +1,62 @@
+require "cloudflare/email/task_base"
+require "cloudflare/email/worker_deployer"
+
+module Cloudflare
+  module Email
+    # `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
+      end
+
+      protected
+
+      def run
+        require_value!(account_id,     "cloudflare.account_id")
+        require_value!(management_token, "cloudflare.api_token (or cloudflare.management_token)")
+        require_value!(ingress_secret, "cloudflare.ingress_secret — run the installer first")
+
+        path = script_path
+        raise "Worker script not found at #{path} — re-run `bin/rails g cloudflare:email:install`" unless File.exist?(path)
+
+        deployer = Cloudflare::Email::WorkerDeployer.new(
+          account_id: account_id, api_token: management_token,
+        )
+
+        say "  Deploying Worker '#{deployer.script_name}'..."
+        deployer.deploy(script_path: path)
+        say "  ✓ Worker script deployed"
+
+        deployer.put_secret("INGRESS_SECRET", ingress_secret)
+        say "  ✓ INGRESS_SECRET set"
+
+        if url.to_s.empty?
+          say "  (skipping RAILS_INGRESS_URL — pass URL=https://... or set RAILS_INGRESS_URL env var)"
+        else
+          deployer.put_secret("RAILS_INGRESS_URL", url)
+          say "  ✓ RAILS_INGRESS_URL set to #{url}"
+        end
+
+        say ""
+        say "  Next: route an address to Worker '#{deployer.script_name}' — either via"
+        say "  `bin/rails cloudflare:email:provision_route ADDRESS=...` or in the dashboard."
+      end
+
+      private
+
+      def script_path
+        opts[:script_path] || default_script_path
+      end
+
+      def url
+        opts[:ingress_url] || ENV["RAILS_INGRESS_URL"].to_s
+      end
+
+      def default_script_path
+        candidates = ["cloudflare-worker/src/index.js", "cloudflare-worker/src/index.ts"]
+        candidates.find { |p| File.exist?(p) } || candidates.first
+      end
+    end
+  end
+end

data/lib/cloudflare/email/dev_tunnel.rb

@@ -0,0 +1,97 @@
+require "cloudflare/email/worker_deployer"
+
+module Cloudflare
+  module Email
+    # `bin/rails cloudflare:email:dev` — spins up a cloudflared tunnel and
+    # updates the deployed Worker's RAILS_INGRESS_URL secret so inbound mail
+    # can flow through to this local Rails server. No wrangler required.
+    class DevTunnel
+      INGRESS_PATH = "/rails/action_mailbox/cloudflare/inbound_emails".freeze
+
+      def self.call(port: 3000, io: $stdout)
+        new(port: port, io: io).call
+      end
+
+      def initialize(port:, io: $stdout)
+        @port       = port
+        @io         = io
+        @tunnel_pid = nil
+      end
+
+      def call
+        check_prerequisites
+
+        require "cloudflare/email/credentials"
+        deployer = Cloudflare::Email::WorkerDeployer.new(
+          account_id: Cloudflare::Email::Credentials.account_id,
+          api_token:  Cloudflare::Email::Credentials.management_token,
+        )
+
+        start_tunnel
+        tunnel_url = wait_for_tunnel_url
+        @io.puts "  Tunnel:  #{tunnel_url}"
+
+        ingress_url = "#{tunnel_url}#{INGRESS_PATH}"
+        deployer.put_secret("RAILS_INGRESS_URL", ingress_url)
+        @io.puts "  Worker '#{deployer.script_name}' RAILS_INGRESS_URL updated → #{ingress_url}"
+        @io.puts ""
+        @io.puts "  Send mail to your routed address; it'll land in this Rails app."
+        @io.puts "  Ctrl-C to stop."
+        @io.puts ""
+
+        trap("INT")  { cleanup; exit 0 }
+        trap("TERM") { cleanup; exit 0 }
+
+        # Stay alive so the tunnel keeps running. The user stops us with Ctrl-C.
+        sleep
+      ensure
+        cleanup
+      end
+
+      private
+
+      def check_prerequisites
+        unless system("command -v cloudflared >/dev/null 2>&1")
+          raise "cloudflared not found in PATH — install from https://developers.cloudflare.com/cloudflared/"
+        end
+        require "cloudflare/email/credentials"
+        if Cloudflare::Email::Credentials.account_id.empty? ||
+           Cloudflare::Email::Credentials.management_token.empty?
+          raise "Missing cloudflare.account_id or cloudflare.api_token in credentials " \
+                "(or CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKEN env vars)"
+        end
+      end
+
+      def start_tunnel
+        @io.puts "  Starting cloudflared tunnel on :#{@port}..."
+        @tunnel_log = File.open("/tmp/cloudflare-email-dev-tunnel.log", "w")
+        @tunnel_pid = spawn(
+          "cloudflared", "tunnel", "--url", "http://127.0.0.1:#{@port}",
+          out: @tunnel_log, err: @tunnel_log,
+        )
+      end
+
+      def wait_for_tunnel_url
+        deadline = Time.now + 30
+        while Time.now < deadline
+          sleep 0.5
+          log = File.read("/tmp/cloudflare-email-dev-tunnel.log") rescue ""
+          if (match = log.match(%r{https://[a-z0-9\-]+\.trycloudflare\.com}))
+            return match[0]
+          end
+        end
+        raise "Timed out waiting for cloudflared to return a tunnel URL"
+      end
+
+      def cleanup
+        if @tunnel_pid
+          Process.kill("TERM", @tunnel_pid) rescue nil
+          Process.wait(@tunnel_pid) rescue nil
+          @tunnel_pid = nil
+        end
+        @tunnel_log&.close
+      end
+
+    end
+  end
+end