Skip to content

A modern, self-hosted backup solution for secure, encrypted backups across local and cloud storage.

13.5 KB
Raw Blame
import fsp from 'fs/promises';
import { constants as fsConstants } from 'fs';
import os from 'os';
import path from 'path';
import type { Database as SqliteDatabase } from 'better-sqlite3';
import { SettingsStore } from '../stores/SettingsStore';
import { StorageStore } from '../stores/StorageStore';
import { appPaths } from '../utils/AppPaths';
import { cronLogger } from '../utils/logger';
import { configService } from './ConfigService';
import { sealBlob } from '../utils/selfBackup/blobFormat';
import { packPayload, computeFingerprint, PlutonEdition } from '../utils/selfBackup/payload';
import { readSelfBackupState, writeSelfBackupState } from '../utils/selfBackup/state';
import { resolveSelfBackup } from '../utils/selfBackup/settings';
import { rcloneCopyTo, rcloneDeleteFile, rcloneLsJson } from '../utils/rclone/helpers';
import { jobQueue } from '../jobs/JobQueue';
import { SELF_BACKUP_JOB_NAME } from '../jobs/systemJobs';
import { AppError } from '../utils/AppError';
import { normalizeStorageName } from '../utils/helpers';
import { IntegrationTypes, SelfBackupSettings } from '../types/settings';
import { NotificationChannelResolver } from '../notifications/channels/NotificationChannelResolver';
import { SelfBackupFailedNotification } from '../notifications/templates/email/backup/SelfBackupFailedNotification';

const RCLONE_TIMEOUT_MS = 120_000;

const BLOB_PREFIX = 'pluton-';
const BLOB_SUFFIX = '.pluton';
const BLOB_NAME_RE = /^pluton-.*\.pluton$/;
const SIDECAR_NAME = 'pluton-recovery.json';

export type SelfBackupRunStatus = 'disabled' | 'skipped' | 'uploaded';

/** The rclone remote behind a storage. `name` is the config section, not the display name. */
interface SelfBackupRemote {
	name: string;
	isLocal: boolean;
}

export interface SelfBackupRunResult {
	status: SelfBackupRunStatus;
	blobName?: string;
}

export interface SelfBackupBlob {
	name: string;
	size: number;
	modTime?: string;
}

export interface SelfBackupStatus extends SelfBackupSettings {
	lastRunAt?: string;
	lastSuccessAt?: string;
	lastError?: string | null;
	lastBlobName?: string;
	running: boolean;
}

export class SelfBackupService {
	constructor(
		protected settingsStore: SettingsStore,
		protected storageStore: StorageStore,
		protected sqlite: SqliteDatabase,
		protected edition: PlutonEdition
	) {}

	protected async resolveSettings(): Promise<SelfBackupSettings> {
		const settingsRow = await this.settingsStore.getFirst();
		return resolveSelfBackup(settingsRow?.settings);
	}

	async getStatus(): Promise<SelfBackupStatus> {
		const settings = await this.resolveSettings();
		const state = readSelfBackupState();
		return {
			...settings,
			lastRunAt: state.lastRunAt,
			lastSuccessAt: state.lastSuccessAt,
			lastError: state.lastError,
			lastBlobName: state.lastBlobName,
			running: jobQueue.hasPending(SELF_BACKUP_JOB_NAME),
		};
	}

	/**
	 * Interval gate. SYSTEM_JOBS is a static array read once at startup, so a
	 * user-configurable interval can't be a cron expression. The task ticks hourly
	 * and asks this instead.
	 */
	async isDue(): Promise<boolean> {
		const settings = await this.resolveSettings();
		if (!settings.enabled) return false;

		const { lastSuccessAt } = readSelfBackupState();
		if (!lastSuccessAt) return true;

		const elapsedMs = Date.now() - new Date(lastSuccessAt).getTime();
		return elapsedMs >= settings.intervalHours * 60 * 60 * 1000;
	}

	async run(opts: { force?: boolean } = {}): Promise<SelfBackupRunResult> {
		const settings = await this.resolveSettings();
		if (!settings.enabled) {
			return { status: 'disabled' };
		}

		const fingerprint = computeFingerprint();
		if (!opts.force && fingerprint === readSelfBackupState().lastFingerprint) {
			cronLogger.info('[SelfBackup] Nothing changed since the last upload. Skipping.');
			const skippedAt = new Date().toISOString();
			writeSelfBackupState({ lastRunAt: skippedAt, lastSuccessAt: skippedAt, lastError: null });
			return { status: 'skipped' };
		}

		// The name is user-editable after save, so the zod check at save time isn't enough.
		const remote = await this.resolveRemote(settings);
		await this.assertLocalTargetUsable(remote, settings.path);

		const tmpDir = await fsp.mkdtemp(path.join(appPaths.getTempDir(), 'self-backup-'));
		try {
			const blobName = `${BLOB_PREFIX}${new Date().toISOString().replace(/[:.]/g, '-')}${BLOB_SUFFIX}`;
			const snapshotPath = path.join(tmpDir, 'pluton.db');

			const dbPageCount = this.vacuumInto(snapshotPath);
			const tar = await packPayload({
				dbSnapshotPath: snapshotPath,
				edition: this.edition,
				dbPageCount,
			});
			const blob = sealBlob(tar, configService.config.ENCRYPTION_KEY);

			const blobPath = path.join(tmpDir, blobName);
			await fsp.writeFile(blobPath, blob, { mode: 0o600 });

			const destDir = this.remoteDir(remote, settings.path);
			await rcloneCopyTo(blobPath, this.remoteFile(destDir, blobName), undefined, {
				timeoutMs: RCLONE_TIMEOUT_MS,
			});

			await this.uploadSidecar(tmpDir, destDir, blobName);
			await this.applyRetention(destDir, settings.retention);

			const finishedAt = new Date().toISOString();
			writeSelfBackupState({
				lastRunAt: finishedAt,
				lastSuccessAt: finishedAt,
				lastError: null,
				lastFingerprint: fingerprint,
				lastBlobName: blobName,
			});

			cronLogger.info(`[SelfBackup] Uploaded ${blobName} (${blob.length} bytes) to ${destDir}`);
			return { status: 'uploaded', blobName };
		} catch (error: any) {
			// Throw: JobQueue retries, and a silent failure here is only discovered during a disaster.
			writeSelfBackupState({
				lastRunAt: new Date().toISOString(),
				lastError: error?.message || 'Unknown error',
			});
			cronLogger.error(`[SelfBackup] Backup failed: ${error?.message}`);
			await this.notifyFailure(error);
			throw error;
		} finally {
			await fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
		}
	}

	/**
	 * Email the admin when a run fails, if the failure-notification toggle is on and an email
	 * integration is connected. Wrapped so a notification problem can never mask or replace the
	 * original backup error.
	 */
	protected async notifyFailure(error: any): Promise<void> {
		try {
			const settingsRow = await this.settingsStore.getFirst();
			const appSettings = settingsRow?.settings;
			const selfBackup = resolveSelfBackup(appSettings);
			if (!selfBackup.notifyOnFailure) return;

			const adminEmail = appSettings?.admin_email;
			if (!adminEmail) {
				cronLogger.warn('[SelfBackup] Failure notification is on but no admin email is set.');
				return;
			}

			const integration = appSettings?.integration ?? {};
			const emailTypes: IntegrationTypes[] = [
				'smtp',
				'sendgrid',
				'mailgun',
				'brevo',
				'resend',
				'awsSes',
			];
			const channelType = emailTypes.find(type => integration[type]?.connected);
			if (!channelType) {
				cronLogger.warn(
					'[SelfBackup] Failure notification is on but no email integration is connected.'
				);
				return;
			}

			const channel = await NotificationChannelResolver.getChannel(channelType);
			const notification = new SelfBackupFailedNotification({
				appTitle: appSettings?.title || 'Pluton',
				error: error?.message || 'Unknown error',
				hostname: os.hostname(),
				storageName: selfBackup.storageName,
				failedAt: new Date(),
			});
			const res = await channel.send(notification, { emails: adminEmail });
			if (!res?.success) {
				cronLogger.error(`[SelfBackup] Failure notification email failed: ${res?.result}`);
			} else {
				cronLogger.info('[SelfBackup] Failure notification email sent to admin.');
			}
		} catch (err: any) {
			cronLogger.error(`[SelfBackup] Could not send failure notification: ${err?.message}`);
		}
	}

	/**
	 * A read-transaction snapshot: everything committed to the WAL at this instant, in a
	 * fresh checkpointed standalone file with no -wal beside it. Never a raw file copy,
	 * which is either stale (main file only) or torn (main + wal under a live writer).
	 *
	 * Refuses an existing destination, hence the mkdtemp + unique name from the caller.
	 */
	protected vacuumInto(destPath: string): number {
		let pageCount = 0;
		try {
			const row = this.sqlite.pragma('page_count', { simple: true });
			pageCount = typeof row === 'number' ? row : 0;
		} catch {
			pageCount = 0;
		}
		this.sqlite.prepare('VACUUM INTO ?').run(destPath);
		return pageCount;
	}

	/** The built-in local storage is named "Local Storage" but its rclone section is "local". */
	protected async resolveRemote(settings: SelfBackupSettings): Promise<SelfBackupRemote> {
		const storage = await this.storageStore.getById(settings.storageId);
		if (!storage) {
			throw new AppError(
				400,
				`The storage selected for Pluton backup no longer exists (id: ${settings.storageId}).`
			);
		}
		return {
			name: storage.id === 'local' ? 'local' : normalizeStorageName(storage.name),
			isLocal: storage.type === 'local',
		};
	}

	/**
	 * rclone resolves a relative root against its own working directory, so a local target
	 * must keep its leading slash. A cloud remote must not have one.
	 */
	protected remoteDir(remote: SelfBackupRemote, targetPath: string): string {
		const trimmed = targetPath.replace(/\/+$/g, '');
		const cleaned = remote.isLocal ? trimmed : trimmed.replace(/^\/+/, '');
		return `${remote.name}:${cleaned}`;
	}

	/**
	 * rclone would create a missing local directory and report success, so a path that is not
	 * mounted into the container silently backs up into the container itself.
	 */
	protected async assertLocalTargetUsable(
		remote: SelfBackupRemote,
		targetPath: string
	): Promise<void> {
		if (!remote.isLocal) return;

		const dir = targetPath.replace(/\/+$/g, '');
		if (!dir) {
			throw new AppError(400, 'Select a folder on the local storage for Pluton backup.');
		}

		try {
			const stat = await fsp.stat(dir);
			if (!stat.isDirectory()) throw new Error('not a directory');
			await fsp.access(dir, fsConstants.W_OK);
		} catch {
			throw new AppError(
				400,
				`The Pluton backup folder "${dir}" does not exist or is not writable. In Docker, bind-mount it into the container as a read-write volume.`
			);
		}
	}

	/**
	 * Join a filename onto a remote dir.
	 *
	 * An empty configured path makes destDir `remote:`, and a naive `${destDir}/${name}`
	 * would yield `remote:/name`, a leading slash that means the filesystem root on a
	 * local remote rather than the remote's own root.
	 */
	protected remoteFile(destDir: string, fileName: string): string {
		return destDir.endsWith(':') ? `${destDir}${fileName}` : `${destDir}/${fileName}`;
	}

	/**
	 * Lets `--list` say "a backup from this morning, host nas-01" rather than making the
	 * user know a path. No secrets in it.
	 */
	protected async uploadSidecar(tmpDir: string, destDir: string, blobName: string): Promise<void> {
		const sidecar = {
			hostname: os.hostname(),
			plutonVersion: process.env.APP_VERSION || 'unknown',
			edition: this.edition,
			updatedAt: new Date().toISOString(),
			latestBlob: blobName,
		};
		const sidecarPath = path.join(tmpDir, SIDECAR_NAME);
		await fsp.writeFile(sidecarPath, JSON.stringify(sidecar, null, 2));
		await rcloneCopyTo(sidecarPath, this.remoteFile(destDir, SIDECAR_NAME), undefined, {
			timeoutMs: RCLONE_TIMEOUT_MS,
		});
	}

	/**
	 * List the backup blobs currently on the configured storage
	 */
	async listBackups(): Promise<SelfBackupBlob[]> {
		const settings = await this.resolveSettings();
		if (!settings.storageId) return [];

		const remote = await this.resolveRemote(settings);
		const destDir = this.remoteDir(remote, settings.path);
		const items = await rcloneLsJson(destDir, undefined, { timeoutMs: RCLONE_TIMEOUT_MS });
		return items
			.filter(item => !item.IsDir && BLOB_NAME_RE.test(item.Name))
			.map(item => ({ name: item.Name, size: item.Size, modTime: item.ModTime }))
			.sort((a, b) => b.name.localeCompare(a.name));
	}

	/**
	 * Copy a single backup blob down to a local temp file for streaming to the client.
	 */
	async downloadBackup(
		blobName: string
	): Promise<{ localPath: string; cleanup: () => Promise<void> }> {
		if (!BLOB_NAME_RE.test(blobName)) {
			throw new AppError(400, 'Invalid backup name.');
		}

		const settings = await this.resolveSettings();
		const remote = await this.resolveRemote(settings);
		const destDir = this.remoteDir(remote, settings.path);

		const tmpDir = await fsp.mkdtemp(path.join(appPaths.getTempDir(), 'self-backup-dl-'));
		const localPath = path.join(tmpDir, blobName);
		try {
			await rcloneCopyTo(this.remoteFile(destDir, blobName), localPath, undefined, {
				timeoutMs: RCLONE_TIMEOUT_MS,
			});
		} catch (error) {
			await fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
			throw error;
		}

		return {
			localPath,
			cleanup: () => fsp.rm(tmpDir, { recursive: true, force: true }).catch(() => {}),
		};
	}

	/** Failures here are logged and swallowed, since the blob is already safely uploaded. */
	protected async applyRetention(destDir: string, retention: number): Promise<void> {
		try {
			const items = await rcloneLsJson(destDir, undefined, { timeoutMs: RCLONE_TIMEOUT_MS });
			const blobs = items
				.filter(item => !item.IsDir && BLOB_NAME_RE.test(item.Name))
				// Names are ISO timestamps, so lexical desc == newest first.
				.sort((a, b) => b.Name.localeCompare(a.Name));

			for (const stale of blobs.slice(retention)) {
				try {
					await rcloneDeleteFile(this.remoteFile(destDir, stale.Name), undefined, {
						timeoutMs: RCLONE_TIMEOUT_MS,
					});
					cronLogger.info(`[SelfBackup] Retention removed ${stale.Name}`);
				} catch (error: any) {
					cronLogger.error(`[SelfBackup] Could not delete ${stale.Name}: ${error?.message}`);
				}
			}
		} catch (error: any) {
			cronLogger.error(`[SelfBackup] Retention pass failed: ${error?.message}`);
		}
	}
}