cloudflare-email 0.1.0 → 0.3.0

data/lib/tasks/cloudflare_email.rake

@@ -6,16 +6,17 @@ namespace :cloudflare do
       exit Cloudflare::Email::Doctor.call
     end
 
-    desc "Send a test email via the current Cloudflare Email config (TO=addr FROM=addr)"
+    desc "Send a real test email (both FROM=addr and TO=addr are required)"
     task send_test: :environment do
       require "cloudflare/email/send_test"
       exit Cloudflare::Email::SendTest.call(to: ENV["TO"], from: ENV["FROM"])
     end
 
-    desc "Deploy the Worker via Cloudflare API (no wrangler/Node required). URL=https://... sets RAILS_INGRESS_URL"
+    desc "Deploy the Worker via Cloudflare API. URL=https://... sets RAILS_INGRESS_URL; SCRIPT=path overrides the Worker source"
     task deploy_worker: :environment do
       require "cloudflare/email/deploy_worker_task"
-      exit Cloudflare::Email::DeployWorkerTask.call(ingress_url: ENV["URL"])
+      exit Cloudflare::Email::DeployWorkerTask.call(ingress_url: ENV["URL"], script_path: ENV["SCRIPT"],
+        delivery_mode: ENV.fetch("INBOUND_DELIVERY_MODE", "durable"))
     end
 
     desc "Create Cloudflare Email Routing rule: ADDRESS=addr@domain → env-scoped Worker (WORKER=name to override)"
@@ -27,7 +28,7 @@ namespace :cloudflare do
       )
     end
 
-    desc "Point the zone's catch-all rule at the env-scoped Worker (DOMAIN=in.example.com [WORKER=name])"
+    desc "Point a zone-wide catch-all at the env-scoped Worker (DOMAIN=example.com [WORKER=name])"
     task provision_catchall: :environment do
       require "cloudflare/email/provision_catchall_task"
       exit Cloudflare::Email::ProvisionCatchallTask.call(
@@ -41,5 +42,42 @@ namespace :cloudflare do
       require "cloudflare/email/dev_tunnel"
       Cloudflare::Email::DevTunnel.call(port: ENV.fetch("PORT", "3000").to_i)
     end
+
+    desc "Process one batch of outbound delivery events using config.x.cloudflare_email.event_handler"
+    task consume_events: :environment do
+      require "cloudflare/email/consume_events_task"
+      settings = Rails.application.config.x.cloudflare_email
+      exit Cloudflare::Email::ConsumeEventsTask.call(
+        handler: settings.event_handler,
+        domains: settings.event_domains,
+        batch_size: Integer(ENV.fetch("BATCH_SIZE", "5"), 10),
+      )
+    end
+
+    desc "Send a prepared durable operation using OPERATION_KEY (no new message is generated)"
+    task deliver: :environment do
+      require "cloudflare/email/send_job"
+      delivery = Cloudflare::Email::SendJob.perform_now(
+        Cloudflare::Email::Credentials.account_id, ENV.fetch("OPERATION_KEY"))
+      puts "operation=#{delivery.operation_key} state=#{delivery.state}"
+    end
+
+    desc "Replay durable outbound receipts for the configured account (optional MESSAGE_ID)"
+    task replay_events: :environment do
+      require "cloudflare/email/replay_events_job"
+      count = Cloudflare::Email::ReplayEventsJob.perform_now(
+        Cloudflare::Email::Credentials.account_id, ENV["MESSAGE_ID"])
+      puts "Replayed #{count} receipt(s)."
+    end
+
+    desc "List prepared or uncertain outbound operations requiring dispatch or operator review"
+    task pending_deliveries: :environment do
+      require "cloudflare/email/active_record"
+      Cloudflare::Email::ActiveRecord::OutboundDelivery.where(
+        account_id: Cloudflare::Email::Credentials.account_id,
+        state: %w[prepared sending unknown partial]).find_each do |delivery|
+        puts "operation=#{delivery.operation_key} state=#{delivery.state} updated_at=#{delivery.updated_at.iso8601}"
+      end
+    end
   end
 end

data/lib/tasks/cloudflare_email_diagnostics.rake

@@ -0,0 +1,11 @@
+namespace :cloudflare do
+  namespace :email do
+    desc "Inspect routing without changes (ADDRESS=addr [WORKER_NAME=name] [ACCOUNT_ID=id]); nonzero if failed or unverified"
+    task check_route: :environment do
+      require "cloudflare/email/check_route_task"
+      exit Cloudflare::Email::CheckRouteTask.call(
+        address: ENV["ADDRESS"], worker_name: ENV["WORKER_NAME"] || ENV["WORKER"], account_id: ENV["ACCOUNT_ID"],
+      )
+    end
+  end
+end

data/templates/deploy-to-cloudflare/.dev.vars.example

@@ -0,0 +1,3 @@
+# Supply these in the Cloudflare deployment form. Never commit real values.
+RAILS_INGRESS_URL=
+INGRESS_SECRET=

data/templates/deploy-to-cloudflare/.gitignore

@@ -0,0 +1,6 @@
+node_modules/
+.wrangler/
+.dev.vars*
+!.dev.vars.example
+.env*
+!.env.example

data/templates/deploy-to-cloudflare/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cole
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/templates/deploy-to-cloudflare/README.md

@@ -0,0 +1,84 @@
+# Cloudflare Email for Rails
+
+Receive email in Rails with the [cloudflare-email gem](https://github.com/cole-robertson/cloudflare-email).
+This template stores inbound mail in private R2, delivers it through a Queue,
+and retries from storage when Rails is unavailable. It includes scheduled
+recovery and Worker logs. No React app or extra server is needed.
+
+[![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cole-robertson/cloudflare-email/tree/main/templates/deploy-to-cloudflare)
+
+## 1. Prepare Rails
+
+Install `gem "cloudflare-email", "~> 0.3.0"` and follow the
+[Rails setup guide](https://github.com/cole-robertson/cloudflare-email/blob/main/docs/getting-started.md).
+Deploy Rails with Action Mailbox storage and routing configured before connecting
+real email. Generate a secret with `openssl rand -hex 32` and configure it as
+`cloudflare.ingress_secret` in Rails credentials or `CLOUDFLARE_INGRESS_SECRET`.
+Keep the same value for the deployment form.
+
+## 2. Deploy the Worker
+
+Click the button and sign in to Cloudflare and GitHub/GitLab as prompted.
+Cloudflare copies this directory into your own repository, provisions the R2
+bucket and Queue, and builds the Worker. Enter:
+
+- **RAILS_INGRESS_URL:** your public HTTPS endpoint, normally
+  `https://your-app.com/rails/action_mailbox/cloudflare/inbound_emails`.
+- **INGRESS_SECRET:** the exact secret you configured in Rails.
+
+Choose distinct Worker, bucket, and Queue names for each app/environment. This
+template has one environment per deployment; deploy separate copies for staging
+and production. R2 and Queues must be available on your account and their usage
+can incur charges. Review Cloudflare's resource and billing prompts.
+
+The form uses `npm run deploy`; no `--env` argument is required for this template.
+After deployment, confirm both bindings, the Queue consumer, and the once-per-minute
+cron are present. Keep the bucket private with no lifecycle rule expiring
+`cloudflare-email/pending/` objects. The Worker has no public email-submit HTTP API.
+
+## 3. Connect an email address
+
+In Cloudflare, enable Email Routing for the intended receiving domain/subdomain
+and complete its required DNS setup. Add an Email Routing rule for your receiving
+address with **Send to a Worker**, selecting the Worker you just deployed.
+The button does not change your MX records, provision addresses in Rails, or
+replace your existing mailbox provider. Use a receiving subdomain when your apex
+domain's email belongs to Google Workspace or Microsoft 365.
+
+If using the gem's managed mailboxes, register the receiving mailbox/address in
+Rails too. Tenant support and domain catch-all receiving remain explicit choices.
+Outbound Email Sending credentials and delivery-event subscriptions are separate
+from this inbound Worker setup.
+
+## 4. Verify and operate
+
+Send to the configured address and verify that Rails retains and routes it.
+In staging, stop Rails, send another message, confirm it remains in R2, restore
+Rails, and confirm one inbox record and removal of the pending object. Verify a
+retry does not duplicate application work. Monitor Worker errors and pending R2
+count/age; Queue depth alone misses mail whose queue retries are exhausted.
+
+Read the [durable delivery and recovery guide](https://github.com/cole-robertson/cloudflare-email/blob/main/templates/worker/docs/durable-inbound.md)
+for recovery limits, retention, failure drills, and the explicit direct fallback.
+In this standalone template, configure bindings at the top level and run
+`npm run deploy` without `--env`. Do not remove storage or cron while mail is pending.
+Delivery is at least once, with Rails deduplication; application handlers must
+also tolerate retries. Configure operational alerts in your monitoring service.
+
+## Updates and local development
+
+Your copied repository belongs to you; gem updates do not update its Worker
+automatically. Review upstream release notes, deploy Rails first, then port Worker
+changes into your copy while preserving your resource names, secrets, and pending
+storage. Keep production resources separate from test resources.
+
+Use Node 22.12+ (or a supported newer version): `npm ci`, `npm test`, and
+`npm run check`. For local development, copy `.dev.vars.example` to `.dev.vars`,
+set local values, and run `npm run dev`. Never commit secrets.
+
+Upstream maintainers: `templates/worker` is the canonical runtime. Run
+`node script/sync_deploy_template.mjs` from the gem repository after modifying its
+runtime, tests, dependencies, or production bindings. CI rejects drift and tests
+this directory after copying it outside the repository, matching Cloudflare's
+subdirectory deployment model. Edit this README directly; generated files are
+marked by the sync script's file list.