Skip to content

Email for professionals and teams

replace workflow with cron

Hieu Nguyen (Jack)a0bbaf331026
diff --git a/.dev.vars.example b/.dev.vars.example
index 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_key
diff --git a/CLAUDE.md b/CLAUDE.md
index 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 pipeline
diff --git a/docs/deployment.md b/docs/deployment.md
index c2f4d5c..7f9bbb7 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -61,7 +61,7 @@ npm install
npm 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 Mailflare
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 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 arriving
diff --git a/env.d.ts b/env.d.ts
index 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.json
index 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.ts
index 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<void
export 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
deleted file mode 100644
index 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.ts
index 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.jsonc
index 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.example
index 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",