cloudflare-email_service 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ae0f87f99efee9db13b22ae4cd2560f75878ee141ce0c34797da94dbb387a37c
-  data.tar.gz: 23cd36dc8c771b45a649d93d6d9385ab76751755b72ffcd795840280c359a53f
+  metadata.gz: 3c8b69fe6e9c96aad0aeff171295d1af48d5e68254c5dc7f3bb238c514c86af5
+  data.tar.gz: bf78b28870b252900cf5784388ff23523e0d69e27cd4b404e6ae45e3430e0e0d
 SHA512:
-  metadata.gz: d5d2e2efb6a2fa418400b2b0d4f26558ef3a647f880d89c81ee71ba1a278d7182ccb8c0db68116a9b106284fb0587b8ebac96a6ba0678aa3da61e7ac6b97b910
-  data.tar.gz: c1db350ec8e6323eb9b7b9f3b5db198c1cf1801c3f790567d0d53c8f34c29ed7d9e2108a9601d9ad9c5b4ba7d9076bcee627856961cbdfb7ea2725f875484b7d
+  metadata.gz: d0257f7558d39424c3d8dfbca70519a24fc3ae4d82293d07afd230a0fb7c948f923e16a84ec03504a689f12ca379688c8274a394e4943e7c40b868275698ca9c
+  data.tar.gz: 1fca3c06a395a2a73f0301d5ca43e4d55984e7da4df352f21c7b66e65b5e70eb98b102aa5f3ce895344a24997cb883f6af7b49a636c603d01d879aa875fb657a

data/CHANGELOG.md

@@ -6,6 +6,31 @@ All notable changes to this project are documented here. The format is based on
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-21
+
+### Changed
+- The bundled Email Worker no longer permanently rejects inbound mail on a
+  transient ingress failure. A `4xx` from the app is still rejected (permanent
+  bounce — a retry won't help), but a `5xx` or network failure now throws, so
+  the sending server retries delivery once the app recovers instead of bouncing
+  legitimate mail during a deploy or brief outage.
+
+### Added
+- A Rails install generator: `bin/rails g cloudflare_email_service:install`
+  writes `config/initializers/cloudflare_email_service.rb` (inbound lines
+  commented out) and prints the remaining setup steps. Generator code lives
+  under `lib/generators` and loads only in a Rails generator context, so the
+  core gem stays Rails-free.
+- Each send now publishes a `deliver.cloudflare_email_service` instrumentation
+  event — through `ActiveSupport::Notifications` when it is loaded, otherwise a
+  no-op. The payload carries the transport, recipient counts, and response
+  status (never message content); a failed send records the exception. Set
+  `config.instrumenter` to plug in a custom one.
+- `RateLimitError#retry_after` exposes the `Retry-After` header from a `429`
+  response as an integer number of seconds (nil when absent or sent as an
+  HTTP-date), so callers can honor Cloudflare's backoff. The README now
+  documents the recommended `deliver_later` + `retry_on` retry pattern.
+
 ## [0.2.0] - 2026-06-19
 
 ### Added

data/README.md

@@ -159,7 +159,14 @@ config.action_mailer.delivery_method = :cloudflare
 
 Credentials come from `CLOUDFLARE_ACCOUNT_ID` / `CLOUDFLARE_API_TOKEN` in the
 environment. To set them in code, choose the SMTP transport, or receive inbound
-mail, use a single initializer:
+mail, use a single initializer. Generate it with
+
+```sh
+bin/rails g cloudflare_email_service:install
+```
+
+which writes the file below (inbound lines commented out) and prints the
+remaining steps — or create it by hand:
 
 ```ruby
 # config/initializers/cloudflare_email_service.rb
@@ -224,6 +231,11 @@ above) and `CLOUDFLARE_EMAIL_INGRESS_SECRET` (matching the app):
 Visiting the worker's URL returns a `{ ok, configured }` health check — a quick
 way to confirm it's deployed and both vars are set.
 
+On a `4xx` (bad signature, wrong media type) the Worker rejects the message
+permanently; on a `5xx` or network failure it fails temporarily, so the sending
+server retries once the app recovers instead of bouncing good mail. Prefer
+zero-downtime deploys, since a long outage can still outlast the retry window.
+
 > [!NOTE]
 > The Worker sends `Content-Type: message/rfc822`; the ingress rejects anything
 > else with `415 Unsupported Media Type`.
@@ -276,6 +288,78 @@ end
 
 ---
 
+## Retries
+
+This client doesn't retry a failed send — it raises and leaves the retry policy
+to you. Cloudflare already retries _accepted_ mail server-side (soft bounces,
+with exponential backoff); retries here are only about getting the request
+accepted in the first place.
+
+In Rails, the idiomatic place is the delivery job: send with `deliver_later` and
+let Active Job retry the transient failures with backoff, while permanent ones
+fail fast. `retry_on` is an Active Job method, so it goes on the delivery job —
+not on the mailer:
+
+```ruby
+# app/jobs/cloudflare_mail_delivery_job.rb
+class CloudflareMailDeliveryJob < ActionMailer::MailDeliveryJob
+  retry_on Cloudflare::EmailService::RateLimitError, # 429
+           Cloudflare::EmailService::ServerError,    # 5xx
+           Cloudflare::EmailService::NetworkError,   # timeout, connection reset, TLS
+           wait: :polynomially_longer, attempts: 5
+end
+
+# app/mailers/application_mailer.rb
+class ApplicationMailer < ActionMailer::Base
+  self.delivery_job = CloudflareMailDeliveryJob
+end
+```
+
+On a `429`, Cloudflare may send a `Retry-After` header. When present it's parsed
+to an integer number of seconds and exposed as `RateLimitError#retry_after`, so
+you can honor the backoff precisely:
+
+```ruby
+rescue Cloudflare::EmailService::RateLimitError => e
+  e.retry_after   # => 30 (seconds), or nil when not provided
+end
+```
+
+---
+
+## Instrumentation
+
+Every send publishes a `deliver.cloudflare_email_service` event. When
+`ActiveSupport::Notifications` is loaded (e.g. in Rails) it's used
+automatically — subscribe to log, time, or meter your sends:
+
+```ruby
+ActiveSupport::Notifications.subscribe("deliver.cloudflare_email_service") do |*args|
+  event = ActiveSupport::Notifications::Event.new(*args)
+  Rails.logger.info(
+    "cloudflare email: transport=#{event.payload[:transport]} " \
+    "to=#{event.payload[:to]} status=#{event.payload[:status]} " \
+    "duration=#{event.duration.round}ms",
+  )
+end
+```
+
+The payload carries `:transport` (`:rest` / `:smtp`), recipient counts (`:to`,
+`:cc`, `:bcc`), and `:status` on success — never addresses, subject, or body. A
+failed send raises through, so the event records the exception (and the send
+still raises to your caller).
+
+Outside Rails, plug in any object with an `instrument(name, payload) { ... }`
+method (the same shape as `ActiveSupport::Notifications`):
+
+```ruby
+Cloudflare::EmailService.configure do |c|
+  c.instrumenter = MyInstrumenter
+end
+```
+
+---
+
 ## Development
 
 ```sh

data/lib/cloudflare/email_service/client.rb

@@ -15,6 +15,8 @@ module Cloudflare
     #   client.send_email(from: "a@x.com", to: "b@y.com",
     #                     subject: "Hi", text: "Hello")
     class Client
+      include Instrumentation
+
       attr_reader :account_id, :api_token, :api_base, :open_timeout, :timeout
 
       def initialize(account_id: nil, api_token: nil, api_base: nil,
@@ -40,7 +42,8 @@ module Cloudflare
       # Sends a pre-built {Message}.
       # @return [Response]
       def deliver(message)
-        post(send_uri, message.validate!.to_h)
+        message.validate!
+        instrument_delivery(:rest, message) { post(send_uri, message.to_h) }
       end
 
       private
@@ -77,7 +80,15 @@ module Cloudflare
         response = Response.new(status: status, body: parse(http_response.body))
         return response if status.between?(200, 299) && response.success?
 
-        raise_error(status, response)
+        raise_error(status, response, retry_after: retry_after_from(http_response))
+      end
+
+      # The `Retry-After` header as a non-negative Integer of seconds, or nil
+      # when absent or given as an HTTP-date rather than a delay.
+      def retry_after_from(http_response)
+        raw = http_response["retry-after"]
+        seconds = Integer(raw.to_s.strip, exception: false)
+        seconds if seconds&.>=(0)
       end
 
       def parse(raw)
@@ -88,12 +99,13 @@ module Cloudflare
         { "success" => false, "errors" => [{ "message" => "non-JSON response body" }] }
       end
 
-      def raise_error(status, response)
+      def raise_error(status, response, retry_after: nil)
         raise error_class_for(status).new(
           summarize(response.errors),
           status: status,
           errors: response.errors,
           response: response,
+          retry_after: retry_after,
         )
       end
 

data/lib/cloudflare/email_service/configuration.rb

@@ -34,6 +34,12 @@ module Cloudflare
       #   Cloudflare Email Worker signs with.
       attr_accessor :ingress_secret
 
+      # @return [#instrument] receives a "deliver.cloudflare_email_service"
+      #   event on each send. Defaults to ActiveSupport::Notifications when it is
+      #   loaded, otherwise a no-op. Assign any object with an
+      #   `instrument(name, payload) { ... }` method.
+      attr_writer :instrumenter
+
       def initialize
         @transport = ENV.fetch("CLOUDFLARE_EMAIL_TRANSPORT", "rest").to_sym
         @account_id = ENV.fetch("CLOUDFLARE_ACCOUNT_ID", nil)
@@ -45,6 +51,24 @@ module Cloudflare
         @timeout = DEFAULT_TIMEOUT
         @ingress_secret = ENV.fetch("CLOUDFLARE_EMAIL_INGRESS_SECRET", nil)
       end
+
+      # Resolved on each read (never memoized) until one is set explicitly, so
+      # ActiveSupport::Notifications is picked up as soon as it loads — even if
+      # an earlier send already resolved the default to the no-op. An explicit
+      # assignment always wins.
+      def instrumenter
+        @instrumenter || default_instrumenter
+      end
+
+      private
+
+      def default_instrumenter
+        if defined?(ActiveSupport::Notifications)
+          ActiveSupport::Notifications
+        else
+          NullInstrumenter
+        end
+      end
     end
   end
 end

data/lib/cloudflare/email_service/errors.rb

@@ -19,11 +19,17 @@ module Cloudflare
       attr_reader :errors
       # @return [Response, nil] the wrapped API response.
       attr_reader :response
+      # @return [Integer, nil] seconds to wait before retrying, parsed from the
+      #   `Retry-After` response header whenever the API sends one (typically a
+      #   429, sometimes a 503). nil when the header is absent or not an integer
+      #   number of seconds.
+      attr_reader :retry_after
 
-      def initialize(message = nil, status: nil, errors: nil, response: nil)
+      def initialize(message = nil, status: nil, errors: nil, response: nil, retry_after: nil)
         @status = status
         @errors = errors || []
         @response = response
+        @retry_after = retry_after
         super(message)
       end
     end

data/lib/cloudflare/email_service/instrumentation.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Cloudflare
+  module EmailService
+    # Fallback instrumenter used when ActiveSupport::Notifications is absent.
+    # Mirrors its `instrument(name, payload) { ... }` signature so the two are
+    # interchangeable, and simply runs the block.
+    module NullInstrumenter
+      module_function
+
+      def instrument(_name, payload = {})
+        yield payload if block_given?
+      end
+    end
+
+    # Shared send instrumentation for the REST and SMTP clients. Wraps each
+    # delivery in a `"deliver.cloudflare_email_service"` event published through
+    # the configured instrumenter (ActiveSupport::Notifications when present,
+    # otherwise a no-op).
+    #
+    # The payload carries the transport and recipient counts — never addresses,
+    # subject, or body — plus the response status on success. On failure the
+    # block raises through, so an ActiveSupport::Notifications instrumenter
+    # records the exception on the event.
+    module Instrumentation
+      EVENT = "deliver.cloudflare_email_service"
+
+      private
+
+      def instrument_delivery(transport, message)
+        payload = {
+          transport: transport,
+          to: recipient_count(message.to),
+          cc: recipient_count(message.cc),
+          bcc: recipient_count(message.bcc),
+        }
+        EmailService.configuration.instrumenter.instrument(EVENT, payload) do
+          response = yield
+          payload[:status] = response.status
+          response
+        end
+      end
+
+      def recipient_count(value)
+        return 0 if value.nil?
+
+        value.is_a?(Array) ? value.length : 1
+      end
+    end
+  end
+end

data/lib/cloudflare/email_service/smtp_client.rb

@@ -13,6 +13,8 @@ module Cloudflare
     #   client.send_email(from: "a@x.com", to: "b@y.com",
     #                     subject: "Hi", text: "Hello")
     class SMTPClient
+      include Instrumentation
+
       # Cloudflare requires the literal string "api_token" as the SMTP username;
       # the password is the API token itself.
       SMTP_USERNAME = "api_token"
@@ -44,19 +46,24 @@ module Cloudflare
       # @return [Response]
       def deliver(message)
         message.validate!
-        envelope = build_envelope(message)
-        envelope.delivery_method(:smtp, smtp_settings)
-        transmit(envelope)
-        accepted(envelope)
-      rescue Net::SMTPAuthenticationError => e
-        raise AuthenticationError, e.message
-      rescue Net::SMTPError => e
-        # Every other SMTP protocol error (busy, syntax, fatal, unknown, ...).
-        raise ServerError, e.message
-      rescue Timeout::Error, Errno::ECONNREFUSED, Errno::ECONNRESET,
-             Errno::EHOSTUNREACH, Errno::ETIMEDOUT, SocketError, IOError,
-             OpenSSL::SSL::SSLError => e
-        raise NetworkError, "SMTP delivery failed: #{e.class}: #{e.message}"
+        # Map errors inside the instrumentation block (not around it) so a
+        # subscriber sees the same gem error classes the caller does — matching
+        # the REST transport, which raises its wrapped errors from within.
+        instrument_delivery(:smtp, message) do
+          envelope = build_envelope(message)
+          envelope.delivery_method(:smtp, smtp_settings)
+          transmit(envelope)
+          accepted(envelope)
+        rescue Net::SMTPAuthenticationError => e
+          raise AuthenticationError, e.message
+        rescue Net::SMTPError => e
+          # Every other SMTP protocol error (busy, syntax, fatal, unknown, ...).
+          raise ServerError, e.message
+        rescue Timeout::Error, Errno::ECONNREFUSED, Errno::ECONNRESET,
+               Errno::EHOSTUNREACH, Errno::ETIMEDOUT, SocketError, IOError,
+               OpenSSL::SSL::SSLError => e
+          raise NetworkError, "SMTP delivery failed: #{e.class}: #{e.message}"
+        end
       end
 
       private

data/lib/cloudflare/email_service/version.rb

@@ -2,6 +2,6 @@
 
 module Cloudflare
   module EmailService
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/lib/cloudflare/email_service.rb

@@ -5,6 +5,7 @@ require_relative "email_service/errors"
 require_relative "email_service/configuration"
 require_relative "email_service/message"
 require_relative "email_service/response"
+require_relative "email_service/instrumentation"
 require_relative "email_service/client"
 require_relative "email_service/smtp_client"
 

data/lib/generators/cloudflare_email_service/install_generator.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+# Generator-only namespace. The flat constant maps the gem name
+# `cloudflare-email_service` onto the `rails g cloudflare_email_service:install`
+# command (Rails derives the namespace from the first module). Runtime code
+# lives under `Cloudflare::EmailService`; this file is loaded only by Rails'
+# generator lookup, never at gem runtime, so the core stays Rails-free.
+module CloudflareEmailService
+  module Generators
+    # Creates the initializer and prints the remaining setup steps.
+    #
+    #   bin/rails g cloudflare_email_service:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Create a Cloudflare Email Service initializer and print the setup steps."
+
+      def create_initializer
+        template "cloudflare_email_service.rb",
+                 "config/initializers/cloudflare_email_service.rb"
+      end
+
+      def print_next_steps
+        say "\ncloudflare-email_service installed.\n", :green
+        say <<~STEPS
+          Next steps:
+
+            1. Point ActionMailer at Cloudflare (e.g. config/environments/production.rb):
+                 config.action_mailer.delivery_method = :cloudflare
+
+            2. Set credentials — in the initializer just created, or via the
+               environment: CLOUDFLARE_ACCOUNT_ID (REST only) and CLOUDFLARE_API_TOKEN.
+
+            3. Inbound mail (Action Mailbox), optional — in the initializer,
+               uncomment `ingress_secret` and the `to_prepare` require, then set:
+                 config.action_mailbox.ingress = :cloudflare
+               and deploy the bundled Worker (find it at
+               `Cloudflare::EmailService.worker_template_path`), setting its
+               CLOUDFLARE_EMAIL_INGRESS_URL and CLOUDFLARE_EMAIL_INGRESS_SECRET vars.
+        STEPS
+      end
+    end
+  end
+end

data/lib/generators/cloudflare_email_service/templates/cloudflare_email_service.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Configure the Cloudflare Email Service client. Credentials can also come from
+# the environment (CLOUDFLARE_ACCOUNT_ID / CLOUDFLARE_API_TOKEN), in which case
+# this block is optional.
+Cloudflare::EmailService.configure do |c|
+  c.account_id = Rails.application.credentials.dig(:cloudflare, :account_id)
+  c.api_token  = Rails.application.credentials.dig(:cloudflare, :api_token)
+  # c.transport = :smtp # optional; defaults to :rest (SMTP needs the `mail` gem)
+
+  # Inbound (Action Mailbox) only — must match the Worker's signing secret:
+  # c.ingress_secret = Rails.application.credentials.dig(:cloudflare, :ingress_secret)
+end
+
+# Inbound (Action Mailbox) only — load the :cloudflare ingress. In `to_prepare`
+# so its controller superclass is autoloadable regardless of boot order. Pair it
+# with `config.action_mailbox.ingress = :cloudflare` in your environment config.
+# Rails.application.config.to_prepare do
+#   require "cloudflare/email_service/action_mailbox"
+# end

data/templates/cloudflare_email_worker.js

@@ -48,8 +48,19 @@ export default {
       body: raw,
     });
 
-    // Reject on failure so Cloudflare bounces the message rather than silently
-    // accepting (and dropping) it.
-    if (!response.ok) message.setReject(`ingress error ${response.status}`);
+    if (response.ok) return;
+
+    // 4xx: the app refused this message and a retry won't change the outcome
+    // (bad signature, wrong media type, unprocessable). Reject permanently so
+    // the sender gets a bounce instead of the message being silently dropped.
+    if (response.status >= 400 && response.status < 500) {
+      return message.setReject(`ingress rejected message (${response.status})`);
+    }
+
+    // 5xx (or any other non-2xx): a transient app problem — a deploy, a 502/503,
+    // a brief 500. Throw instead of setReject, exactly as a failed fetch() above
+    // already would, so the message is NOT permanently bounced and the sending
+    // server retries delivery once the app recovers.
+    throw new Error(`ingress temporarily unavailable (${response.status})`);
   },
 };

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cloudflare-email_service
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Elvinas Predkelis
@@ -121,9 +121,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
-description: A small Ruby client for the Cloudflare Email Service with zero runtime
-  dependencies and optional Rails integration (ActionMailer delivery and Action Mailbox
-  inbound).
+description: Send and receive email with the Cloudflare Email Service in Ruby. Zero
+  runtime dependencies, with optional ActionMailer and Action Mailbox adapters for
+  Rails.
 email:
 - elvinas@primevise.com
 executables: []
@@ -139,12 +139,15 @@ files:
 - lib/cloudflare/email_service/configuration.rb
 - lib/cloudflare/email_service/errors.rb
 - lib/cloudflare/email_service/inbound.rb
+- lib/cloudflare/email_service/instrumentation.rb
 - lib/cloudflare/email_service/message.rb
 - lib/cloudflare/email_service/rails.rb
 - lib/cloudflare/email_service/railtie.rb
 - lib/cloudflare/email_service/response.rb
 - lib/cloudflare/email_service/smtp_client.rb
 - lib/cloudflare/email_service/version.rb
+- lib/generators/cloudflare_email_service/install_generator.rb
+- lib/generators/cloudflare_email_service/templates/cloudflare_email_service.rb
 - templates/cloudflare_email_worker.js
 homepage: https://github.com/elvinaspredkelis/cloudflare-email_service
 licenses: