Email for professionals and teams
replace workflow with cron
Hieu Nguyen (Jack)a0bbaf331026
diff --git a/.dev.vars.example b/.dev.vars.exampleindex 4e671f6..ee6cfa1 100644--- a/.dev.vars.example+++ b/.dev.vars.example@@ -1,20 +1,11 @@# Preferred: scoped API token.# This is an app runtime token, not the Cloudflare deploy/build token.CF_TOKEN=your_api_token_with_zone_email_permissions-# Optional account id. Read by the database backup workflow.-# CF_AID=your_account_id-# Optional: lets the admin dashboard trigger the GitHub update workflow.# GITHUB_UPDATE_TOKEN=github_pat_with_actions_write# GITHUB_UPDATE_REPO=owner/repo# GITHUB_UPDATE_REF=main-# Optional: required for manual and scheduled D1 database backups.-# D1_DATABASE_ID=your_d1_database_id--# Omit this when CF_TOKEN also has permission to export the D1 database.-# D1_BACKUP_TOKEN=cloudflare_api_token_allowed_to_export_d1-# Legacy Global API Key alternative. Use this only instead of CF_TOKEN.# CF_API_KEY=your_global_api_keydiff --git a/CLAUDE.md b/CLAUDE.mdindex acd705d..50dfa09 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -28,7 +28,7 @@ Do not deploy with `opennextjs-cloudflare deploy`. The deploy script deliberatel## Architecture-Next.js 16 App Router running on Cloudflare Workers via OpenNext. Drizzle ORM over D1, R2 for raw MIME and attachments, Queues for async mail processing, a Durable Object for realtime, and a Workflow for backups.+Next.js 16 App Router running on Cloudflare Workers via OpenNext. Drizzle ORM over D1, R2 for raw MIME, attachments, and record backups, Queues for async mail processing, a Durable Object for realtime, and a cron trigger for scheduled backups.### worker.ts is the entrypoint@@ -38,7 +38,7 @@ Next.js 16 App Router running on Cloudflare Workers via OpenNext. Drizzle ORM ov- **`email`** — the Cloudflare Email Routing handler. Resolves domain routing rules first (`resolveIncomingMail` in `src/lib/email/incoming.ts`) because `message.setReject()` and `message.forward()` only exist here, then applies optional account-level forwarding (loop-guarded by the `MAILFLARE_FORWARDED_HEADER`), writes raw MIME to R2, and enqueues to `INBOUND_QUEUE`. It never parses mail inline.- **`queue`** — a single consumer for both queues; `isInboundQueueMessage` and `isWebhookRetryMessage` in `worker-utils.ts` discriminate inbound mail, webhook retries, and outbound payloads. Failures `retry({ delaySeconds: 10 })`.-It also re-exports `RealtimeHub` and `DatabaseBackupWorkflow`, which is why those classes must live outside the Next build.+It also re-exports `RealtimeHub`, which is why that class must live outside the Next build.### Mail pipelinediff --git a/docs/deployment.md b/docs/deployment.mdindex c2f4d5c..7f9bbb7 100644--- a/docs/deployment.md+++ b/docs/deployment.md@@ -61,7 +61,7 @@ npm installnpm run deploy:local```-The local deploy command builds the OpenNext application, applies pending D1 migrations, and uploads the complete Worker with Wrangler. The complete Worker is required because `worker.ts` also handles inbound email, queues, workflows, and the real-time Durable Object.+The local deploy command builds the OpenNext application, applies pending D1 migrations, and uploads the complete Worker with Wrangler. The complete Worker is required because `worker.ts` also handles inbound email, queues, scheduled backups, and the real-time Durable Object.To migrate an existing remote D1 database before deploying, use:@@ -73,7 +73,11 @@ Remote migrations require the target account's `database_id` in your local `wran## Database backups-Manual and scheduled backups use the `DATABASE_BACKUP_WORKFLOW` binding declared in `wrangler.jsonc`. Deploy the complete Worker with `npm run deploy` whenever this binding is added or changed.+Mailflare exports its D1 records as JSON and stores the backup files in the configured R2 bucket. A cron trigger in `wrangler.jsonc` runs daily at 02:00 UTC and applies the schedule selected under **Admin → Backups**. Manual backups run the same record export directly from the admin API.++Deploy the complete Worker with `npm run deploy` whenever the cron trigger is added or changed.++After upgrading an existing installation and confirming the cron trigger is active, the old Workflow can be removed with `npx wrangler workflows delete mailflare-database-backup`. Deleting it also removes its historical Workflow instances; backup files in R2 and rows in Mailflare's backup history are unaffected.## Updating Mailflarediff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdindex e682e81..cfeeef4 100644--- a/docs/troubleshooting.md+++ b/docs/troubleshooting.md@@ -39,11 +39,11 @@ For remote migrations after the first deployment:Do not commit that account-specific ID to a reusable public repository.-## Backup binding is missing+## Scheduled backups are not running-Deploy the complete Worker with `npm run deploy`. A local Next.js server or a source-only update does not provision the `DATABASE_BACKUP_WORKFLOW` binding.+Deploy the complete Worker with `npm run deploy`. A local Next.js server or a source-only update does not provision the cron trigger declared in `wrangler.jsonc`.-Also confirm that `CF_AID` and `D1_DATABASE_ID` are set, and that `D1_BACKUP_TOKEN` or `CF_TOKEN` can export the database.+Also confirm that automatic backups are enabled under **Admin → Backups** and that the Worker has its `DB` and `BUCKET` bindings.## Inbound mail is not arrivingdiff --git a/env.d.ts b/env.d.tsindex 2afa03b..9af9aac 100644--- a/env.d.ts+++ b/env.d.ts@@ -14,14 +14,10 @@ interface CloudflareEnv {REALTIME: DurableObjectNamespace<import("./src/lib/realtime/hub").RealtimeHub>;- DATABASE_BACKUP_WORKFLOW?: Workflow<import("./src/lib/backups/types").BackupWorkflowParams>;LOGIN_RATE_LIMIT?: RateLimit;CF_TOKEN?: string;CF_API_KEY?: string;CF_EMAIL?: string;- CF_AID?: string;- D1_DATABASE_ID?: string;- D1_BACKUP_TOKEN?: string;TURNSTILE_SECRET_KEY?: string;GITHUB_UPDATE_TOKEN?: string;GITHUB_UPDATE_REF?: string;diff --git a/package.json b/package.jsonindex de1cfa1..5e14ff1 100644--- a/package.json+++ b/package.json@@ -26,15 +26,6 @@"CF_TOKEN": {"description": "Runtime Cloudflare API token used by Mailflare onboarding to call the Zones and Email Routing APIs. Cloudflare's deploy/build token is not passed to the app, so create this separately at https://dash.cloudflare.com/profile/api-tokens with `Zone Read`, `Email Routing Edit`, `Email Sending Edit`, and `Email Routing Rules Write` permissions for the zones you will connect. Paste only the token secret value, without `Bearer`."},- "CF_AID": {- "description": "Cloudflare account ID. Required for automatic database backups."- },- "D1_DATABASE_ID": {- "description": "Cloudflare D1 database ID for the mailflare database. Required for automatic database backups."- },- "D1_BACKUP_TOKEN": {- "description": "Optional Cloudflare API token allowed to export the target D1 database. Store this as a secret. If omitted, backups reuse CF_TOKEN."- },"TURNSTILE_SECRET_KEY": {"description": "Cloudflare Turnstile secret key used to verify login and first-run registration challenges. Pair with NEXT_PUBLIC_TURNSTILE_SITE_KEY at build time."},diff --git a/src/app/(admin)/backups/utils.ts b/src/app/(admin)/backups/utils.tsindex bc35b09..22c04c6 100644--- a/src/app/(admin)/backups/utils.ts+++ b/src/app/(admin)/backups/utils.ts@@ -31,7 +31,7 @@ export async function saveBackupSettings(settings: BackupSettings): Promise<voidexport async function startBackup(): Promise<void> {const response = await authFetch("/api/backups", { method: "POST" });const data = (await response.json()) as { error?: string };- if (!response.ok) throw new Error(data.error ?? "Failed to start backup");+ if (!response.ok) throw new Error(data.error ?? "Failed to run backup");}export async function removeBackup(id: string): Promise<void> {diff --git a/src/app/api/backups/route.ts b/src/app/api/backups/route.tsindex 8d46ffd..d7e2013 100644--- a/src/app/api/backups/route.ts+++ b/src/app/api/backups/route.ts@@ -1,20 +1,14 @@import { NextResponse } from "next/server";-import { eq } from "drizzle-orm";-import { getDb } from "@/db";-import { backups } from "@/db/schema";import { assertAdmin } from "@/lib/auth/admin";import { requireUser } from "@/lib/auth/cookies";-import { getD1ExportConfigurationStatus } from "@/lib/backups/export";+import { getBackupConfigurationStatus } from "@/lib/backups/export";+import { runDatabaseBackup } from "@/lib/backups/runner";import {createBackupRecord,getBackupSettings,listBackups,updateBackupSettings,} from "@/lib/backups/service";-import {- BackupWorkflowUnavailableError,- getBackupWorkflowBinding,-} from "@/lib/backups/utils";import { getEnv } from "@/lib/cloudflare";import { parseBackupSettingsInput } from "./utils";@@ -35,7 +29,7 @@ export async function GET(request: Request) {return NextResponse.json({settings,backups: backupList,- configuration: getD1ExportConfigurationStatus(env),+ configuration: getBackupConfigurationStatus(env),});} catch {return NextResponse.json({ error: "Forbidden" }, { status: 403 });@@ -57,25 +51,11 @@ export async function PUT(request: Request) {export async function POST(request: Request) {try {const { env, user } = await requireAdmin(request);- const workflow = getBackupWorkflowBinding(env);const backupId = await createBackupRecord(env, "manual", user.id);- try {- await workflow.create({- id: `database-backup-${backupId}`,- params: { backupId, force: true },- });- } catch (error) {- const message = error instanceof Error ? error.message : "Failed to start backup";- await getDb(env)- .update(backups)- .set({ status: "failed", error: message, completedAt: new Date() })- .where(eq(backups.id, backupId));- throw error;- }- return NextResponse.json({ backupId }, { status: 202 });+ await runDatabaseBackup(env, backupId);+ return NextResponse.json({ backupId });} catch (error) {- const message = error instanceof Error ? error.message : "Failed to start backup";- const status = error instanceof BackupWorkflowUnavailableError ? 503 : 400;- return NextResponse.json({ error: message }, { status });+ const message = error instanceof Error ? error.message : "Failed to run backup";+ return NextResponse.json({ error: message }, { status: 400 });}}diff --git a/src/lib/backups/export.ts b/src/lib/backups/export.tsindex 9444ba1..d37c02d 100644--- a/src/lib/backups/export.ts+++ b/src/lib/backups/export.ts@@ -10,7 +10,7 @@ const BACKUP_TABLES: DatabaseBackupTable[] = ["users", "domains", "mailboxes", "const REQUIRED_BACKUP_TABLES: DatabaseBackupTable[] = ["users", "domains", "mailboxes", "mailbox_access", "contacts", "folders", "api_keys", "messages", "message_attachments", "outbound_jobs", "routing_rules", "webhooks", "webhook_deliveries", "sessions", "audit_logs", "backup_settings", "backups", "app_settings", "license_settings"];const INSERT_BATCH_SIZE = 50;-export function getD1ExportConfigurationStatus(_env?: CloudflareEnv) {+export function getBackupConfigurationStatus(_env?: CloudflareEnv) {return { configured: true, missing: [] };}diff --git a/src/lib/backups/runner.ts b/src/lib/backups/runner.tsnew file mode 100644index 0000000..93ae25a--- /dev/null+++ b/src/lib/backups/runner.ts@@ -0,0 +1,75 @@+import { and, eq, inArray, lt } from "drizzle-orm";+import { getDb } from "@/db";+import { backups } from "@/db/schema";+import { exportDatabaseRecords } from "./export";+import { createScheduledBackupIfDue, getBackupSettings } from "./service";+import { BACKUP_PREFIX, createBackupFilename } from "./utils";++export async function runDatabaseBackup(env: CloudflareEnv, backupId: string): Promise<void> {+ const db = getDb(env);+ try {+ await db+ .update(backups)+ .set({ status: "running", startedAt: new Date() })+ .where(eq(backups.id, backupId));++ const content = await exportDatabaseRecords(env.DB);+ const filename = createBackupFilename(new Date());+ const r2Key = `${BACKUP_PREFIX}/${backupId}/${filename}`;+ const object = await env.BUCKET.put(r2Key, content, {+ httpMetadata: { contentType: "application/json" },+ customMetadata: { backupId },+ });++ await db+ .update(backups)+ .set({+ status: "completed",+ filename,+ r2Key,+ size: object.size,+ completedAt: new Date(),+ error: null,+ })+ .where(eq(backups.id, backupId));+ await deleteExpiredBackups(env);+ } catch (error) {+ const message = error instanceof Error ? error.message : "Backup failed";+ await db+ .update(backups)+ .set({ status: "failed", error: message, completedAt: new Date() })+ .where(eq(backups.id, backupId));+ throw error;+ }+}++export async function runScheduledDatabaseBackup(env: CloudflareEnv, now: Date): Promise<void> {+ const backupId = await createScheduledBackupIfDue(env, now);+ if (backupId) {+ await runDatabaseBackup(env, backupId);+ return;+ }+ await deleteExpiredBackups(env);+}++export async function deleteExpiredBackups(env: CloudflareEnv): Promise<number> {+ const settings = await getBackupSettings(env);+ if (!settings?.retentionEnabled) return 0;++ const cutoff = new Date(Date.now() - settings.retentionDays * 86_400_000);+ const db = getDb(env);+ const expired = await db+ .select()+ .from(backups)+ .where(+ and(+ lt(backups.createdAt, cutoff),+ inArray(backups.status, ["completed", "failed"]),+ ),+ );+ for (const backup of expired) {+ if (backup.r2Key) await env.BUCKET.delete(backup.r2Key);+ await db.delete(backups).where(eq(backups.id, backup.id));+ }+ return expired.length;+}diff --git a/src/lib/backups/service.ts b/src/lib/backups/service.tsindex a7f86ed..b248c9a 100644--- a/src/lib/backups/service.ts+++ b/src/lib/backups/service.ts@@ -1,4 +1,4 @@-import { and, desc, eq, gte, lt } from "drizzle-orm";+import { and, desc, eq, gte, inArray, lt } from "drizzle-orm";import { getDb } from "@/db";import { backups, backupSettings } from "@/db/schema";import { newId } from "@/lib/ids";@@ -45,6 +45,7 @@ export async function createScheduledBackupIfDue(env: CloudflareEnv, now: Date):.where(and(eq(backups.trigger, "scheduled"),+ inArray(backups.status, ["queued", "running", "completed"]),gte(backups.createdAt, new Date(start)),lt(backups.createdAt, new Date(end)),),diff --git a/src/lib/backups/types.d.ts b/src/lib/backups/types.d.tsindex 40d081d..775a1ba 100644--- a/src/lib/backups/types.d.ts+++ b/src/lib/backups/types.d.ts@@ -1,17 +1,5 @@export type BackupScheduleType = "daily" | "weekly" | "monthly";-export type BackupWorkflowParams = {- backupId?: string;- force?: boolean;-};--export type BackupWorkflowBinding = {- create(options?: {- id?: string;- params?: BackupWorkflowParams;- }): Promise<unknown>;-};-export type DatabaseBackupTable = "users" | "domains" | "mailboxes" | "mailbox_access" | "contacts" | "folders" | "api_keys" | "messages" | "message_attachments" | "outbound_jobs" | "routing_rules" | "webhooks" | "webhook_deliveries" | "sessions" | "audit_logs" | "backup_settings" | "backups" | "app_settings" | "license_settings" | "email_templates" | "calendar_events" | "auto_reply_deliveries";export type DatabaseRecord = Record<string, string | number | null>;export type DatabaseBackupDocument = { format: "mailflare-database-backup"; version: 1; createdAt: string; tables: Record<DatabaseBackupTable, DatabaseRecord[]>; };diff --git a/src/lib/backups/utils.ts b/src/lib/backups/utils.tsindex ed5097e..6ab6548 100644--- a/src/lib/backups/utils.ts+++ b/src/lib/backups/utils.ts@@ -1,25 +1,8 @@-import type { BackupScheduleType, BackupWorkflowBinding, DatabaseBackupDocument, DatabaseRecord } from "./types";+import type { BackupScheduleType, DatabaseBackupDocument, DatabaseRecord } from "./types";export const BACKUP_SETTINGS_ID = "default";export const BACKUP_PREFIX = "backups/database";-export class BackupWorkflowUnavailableError extends Error {- constructor() {- super(- "Database backups are unavailable because the DATABASE_BACKUP_WORKFLOW binding is missing. Deploy the app with `npm run deploy` so Wrangler applies the workflow configuration.",- );- this.name = "BackupWorkflowUnavailableError";- }-}--export function getBackupWorkflowBinding(env: CloudflareEnv): BackupWorkflowBinding {- const workflow = env.DATABASE_BACKUP_WORKFLOW as BackupWorkflowBinding | undefined;- if (!workflow || typeof workflow.create !== "function") {- throw new BackupWorkflowUnavailableError();- }- return workflow;-}-export function isBackupDue(scheduleType: BackupScheduleType,scheduleValue: number | null,diff --git a/src/lib/backups/workflow.ts b/src/lib/backups/workflow.tsdeleted file mode 100644index 7de0bb9..0000000--- a/src/lib/backups/workflow.ts+++ /dev/null@@ -1,91 +0,0 @@-import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers";-import { and, eq, inArray, lt } from "drizzle-orm";-import { getDb } from "@/db";-import { backups } from "@/db/schema";-import { exportDatabaseRecords } from "./export";-import { createScheduledBackupIfDue, getBackupSettings } from "./service";-import type { BackupWorkflowParams } from "./types";-import {- BACKUP_PREFIX,- createBackupFilename,-} from "./utils";--export class DatabaseBackupWorkflow extends WorkflowEntrypoint<CloudflareEnv, BackupWorkflowParams> {- async run(event: Readonly<WorkflowEvent<BackupWorkflowParams>>, step: WorkflowStep) {- let backupId = event.payload?.backupId;- if (!backupId) {- backupId = await step.do("Check backup schedule", async () =>- createScheduledBackupIfDue(this.env, event.timestamp),- );- }- if (!backupId) {- const retention = await step.do("Delete expired backups", async () => this.deleteExpiredBackups());- return { skipped: true, ...retention };- }-- try {- await step.do("Mark backup running", async () => {- await getDb(this.env)- .update(backups)- .set({ status: "running", startedAt: new Date() })- .where(eq(backups.id, backupId));- });-- const stored = await step.do("Store backup in R2", async () => {- const content = await exportDatabaseRecords(this.env.DB);- const filename = createBackupFilename(new Date());- const r2Key = `${BACKUP_PREFIX}/${backupId}/${filename}`;- const object = await this.env.BUCKET.put(r2Key, content, {- httpMetadata: { contentType: "application/json" },- customMetadata: { backupId },- });- return { filename, r2Key, size: object.size };- });-- await step.do("Complete backup", async () => {- await getDb(this.env)- .update(backups)- .set({- status: "completed",- filename: stored.filename,- r2Key: stored.r2Key,- size: stored.size,- completedAt: new Date(),- error: null,- })- .where(eq(backups.id, backupId));- });-- await step.do("Delete expired backups", async () => this.deleteExpiredBackups());- return { backupId, ...stored };- } catch (error) {- const message = error instanceof Error ? error.message : "Backup failed";- await getDb(this.env)- .update(backups)- .set({ status: "failed", error: message, completedAt: new Date() })- .where(eq(backups.id, backupId));- throw error;- }- }-- private async deleteExpiredBackups(): Promise<{ deleted: number }> {- const settings = await getBackupSettings(this.env);- if (!settings?.retentionEnabled) return { deleted: 0 };- const cutoff = new Date(Date.now() - settings.retentionDays * 86_400_000);- const db = getDb(this.env);- const expired = await db- .select()- .from(backups)- .where(- and(- lt(backups.createdAt, cutoff),- inArray(backups.status, ["completed", "failed"]),- ),- );- for (const backup of expired) {- if (backup.r2Key) await this.env.BUCKET.delete(backup.r2Key);- await db.delete(backups).where(eq(backups.id, backup.id));- }- return { deleted: expired.length };- }-}diff --git a/worker.ts b/worker.tsindex f7bbc8e..9121af8 100644--- a/worker.ts+++ b/worker.ts@@ -15,8 +15,8 @@ import {getAccountForwardingDestination,MAILFLARE_FORWARDED_HEADER,} from "./src/lib/email/account-forwarding";+import { runScheduledDatabaseBackup } from "./src/lib/backups/runner";export { RealtimeHub } from "./src/lib/realtime/hub";-export { DatabaseBackupWorkflow } from "./src/lib/backups/workflow";export default {async fetch(request: Request, env: CloudflareEnv, ctx: ExecutionContext) {@@ -93,4 +93,8 @@ export default {}}},++ async scheduled(controller: ScheduledController, env: CloudflareEnv, ctx: ExecutionContext) {+ ctx.waitUntil(runScheduledDatabaseBackup(env, new Date(controller.scheduledTime)));+ },} satisfies ExportedHandler<CloudflareEnv>;diff --git a/wrangler.jsonc b/wrangler.jsoncindex 6bf960e..21a7c75 100644--- a/wrangler.jsonc+++ b/wrangler.jsonc@@ -37,14 +37,9 @@],},],- "workflows": [- {- "name": "mailflare-database-backup",- "binding": "DATABASE_BACKUP_WORKFLOW",- "class_name": "DatabaseBackupWorkflow",- "schedules": ["0 2 * * *"],- },- ],+ "triggers": {+ "crons": ["0 2 * * *"],+ },"ratelimits": [{"name": "LOGIN_RATE_LIMIT",diff --git a/wrangler.jsonc.example b/wrangler.jsonc.exampleindex b47f7dc..d3acee5 100644--- a/wrangler.jsonc.example+++ b/wrangler.jsonc.example@@ -20,14 +20,9 @@"service": "mailflare",},],- "workflows": [- {- "name": "mailflare-database-backup",- "binding": "DATABASE_BACKUP_WORKFLOW",- "class_name": "DatabaseBackupWorkflow",- "schedules": ["0 2 * * *"],- },- ],+ "triggers": {+ "crons": ["0 2 * * *"],+ },"ratelimits": [{"name": "LOGIN_RATE_LIMIT",