A modern, self-hosted backup solution for secure, encrypted backups across local and cloud storage.
import os from 'os';
import fs from 'fs';
import { EventEmitter } from 'events';
import {
getBackupPlanStats,
runResticCommand,
ResticCommandError,
} from '../../utils/restic/restic';
import { generateResticRepoPath } from '../../utils/restic/helpers';
import { classifyResticExitCode, isResticBackupWarning } from '../../utils/restic/exitCodes';
import { processManager } from '../ProcessManager';
import { PruneHandler } from './PruneHandler';
import { ProgressManager } from '../ProgressManager';
import { appPaths } from '../../utils/AppPaths';
import { BackupPlanArgs } from '../../types/plans';
import { runScriptsForEvent } from '../../utils/executeUserScript';
import { configService } from '../../services/ConfigService';
import { ReplicationOrchestrator } from './ReplicationOrchestrator';
import { BackupMirror, BackupRunConfig } from '../../types/backups';
import { checkDestinationSpace } from '../../utils/checkDestinationSpace';
type ResticArgsAndEnv = {
resticArgs: string[];
resticEnv: Record<string, string>;
};
// A backup that gives no output for one hour is stuck (sleep, VPN drop, NAS offline).
// The watchdog kills it so the job queue does not lock forever.
const RESTIC_STALL_TIMEOUT_MS = 60 * 60 * 1000;
export class BackupHandler {
private runningBackups = new Set<string>();
private cancelledBackups = new Set<string>();
// private backupAttempts = new Map<string, number>();
private progressManager: ProgressManager;
private replicationOrchestrator?: ReplicationOrchestrator;
constructor(protected emitter: EventEmitter) {
this.progressManager = new ProgressManager(appPaths.getProgressDir());
this.initializeProgressManager();
}
private getReplicationOrchestrator(): ReplicationOrchestrator {
if (!this.replicationOrchestrator) {
this.replicationOrchestrator = new ReplicationOrchestrator(
this.emitter,
this.progressManager,
this.cancelledBackups
);
}
return this.replicationOrchestrator;
}
private async initializeProgressManager(): Promise<void> {
try {
await this.progressManager.initialize();
} catch (error) {
console.warn(`Failed to initialize progress manager: ${error}`);
}
}
/**
* Executes the backup process of a plan.
* @param planId - The ID of the backup plan.
* @param backupId - The Pre-generated ID of the backup.
* @param options - The options for the backup.
* @returns The output of the backup process.
*/
async execute(
planId: string,
backupId: string,
options: BackupPlanArgs,
retryInfo: { attempts: number; maxAttempts: number },
runConfig?: BackupRunConfig
): Promise<string> {
// Prevent the same plan from running concurrently.
if (this.runningBackups.has(planId)) {
throw new Error(`Backup is already in progress for plan: ${planId}`);
}
this.runningBackups.add(planId);
// Initialize progress file
try {
await this.progressManager.initializeProgress(planId, backupId, retryInfo);
} catch (error) {
console.warn(`Failed to initialize progress file: ${error}`);
}
// If this is a retry, log the attempt number to the progress file.
if (retryInfo.attempts > 0) {
await this.updateProgress(
planId,
backupId,
'pre-backup',
`RETRY_ATTEMPT_${retryInfo.attempts}_OF_${retryInfo.maxAttempts}_START`,
false
);
}
try {
// --- 1. PRE-BACKUP PHASE ---
const resticArgsAndEnv = this.createResticBackupArgs(planId, options);
await this.preBackupPhase(planId, backupId, options, resticArgsAndEnv, runConfig);
if (this.cancelledBackups.has(planId + backupId)) {
throw new Error('BACKUP_CANCELLED: Backup was cancelled');
}
// --- 2. BACKUP PHASE ---
const result = await this.executeBackupPhase(
planId,
backupId,
options,
resticArgsAndEnv,
runConfig
);
if (this.cancelledBackups.has(planId + backupId)) {
throw new Error('BACKUP_CANCELLED: Backup was cancelled');
}
// --- 3. POST-BACKUP PHASE ---
await this.postBackupPhase(planId, backupId, options, runConfig);
// --- 4. REPLICATION PHASE ---
if (
options.settings?.replication?.enabled &&
options.settings.replication.storages?.length > 0
) {
await this.getReplicationOrchestrator().run(planId, backupId, options);
}
// Mark as completed
await this.progressManager.markCompleted(planId, backupId, true);
// Emit backup_complete AFTER the entire flow (including replication) is done.
// This sets inProgress=false in the DB so the frontend hides the progress bar.
const progressData = await this.progressManager.getResticProgress(planId, backupId);
this.emitter.emit('backup_complete', {
planId,
backupId,
success: true,
summary: progressData,
});
// Run After Backup scripts
await this.afterBackup(planId, backupId, options);
return result;
} catch (error: any) {
// --- 4. CENTRALIZED ERROR HANDLING ---
const errorMessage = error instanceof Error ? error.message : 'Unknown execution error';
// If Cancelled by the user, do not retry or mark as failed.
const isCancelled =
errorMessage.startsWith('BACKUP_CANCELLED:') ||
this.cancelledBackups.has(planId + backupId);
if (isCancelled) {
return '';
}
// If this is not the final attempt, log that a retry will be scheduled.
// const isFinalAttempt = retryInfo.attempts + 1 === retryInfo.maxAttempts;
// If restic fails with code 10 or 12, retry cannot fix them, so fail immediately
const resticExitCode = (error as ResticCommandError)?.code;
const classification = classifyResticExitCode(resticExitCode);
const isNonRetryable =
(resticExitCode !== undefined && !classification.retryable) || error?.retryable === false;
const attemptsExhausted = retryInfo.attempts + 1 >= retryInfo.maxAttempts;
const permanentlyFailed = attemptsExhausted || isNonRetryable;
// Mark as failed
await this.progressManager.markCompleted(
planId,
backupId,
false,
errorMessage,
permanentlyFailed
);
// Emit backup_complete with failure so the DB sets inProgress=false.
// Only emit for permanent failures. For retryable failures, the backup
// stays inProgress so the frontend keeps showing the progress bar.
if (permanentlyFailed) {
this.emitter.emit('backup_complete', {
planId,
backupId,
success: false,
summary: null,
});
}
if (!permanentlyFailed) {
await this.updateProgress(
planId,
backupId,
'retry',
`BACKUP_RETRY_${retryInfo.attempts + 1}_OF_${retryInfo.maxAttempts}_SCHEDULED`,
false
);
}
// Emit the 'error' event for the listener to log the attempt failure.
this.emitter.emit('backup_error', {
planId,
backupId,
error: errorMessage,
});
// Run post-failure scripts.
if (permanentlyFailed) {
await this.afterBackupFailure(planId, backupId, options);
await this.afterBackup(planId, backupId, options);
} else {
await this.afterBackupError(planId, backupId, options);
}
// Re-throw the error so the JobProcessor's catch block is triggered and decides whether to retry.
// Preserve the restic exit code and a `retryable` flag so the JobProcessor
// can skip retries for permanent failures
const rethrown: ResticCommandError & { retryable?: boolean } = new Error(errorMessage);
rethrown.code = resticExitCode;
rethrown.retryable = !isNonRetryable;
throw rethrown;
} finally {
// This block runs regardless of success or failure, ensuring we always clean up.
this.runningBackups.delete(planId);
this.cancelledBackups.delete(planId + backupId);
}
}
/**
* Pre-backup phase - dry run, validation, and preparation
*/
private async preBackupPhase(
planId: string,
backupId: string,
options: Record<string, any>,
resticArgsAndEnv: ResticArgsAndEnv,
runConfig?: BackupRunConfig
): Promise<void> {
// Update progress: Pre-backup start
await this.updateProgress(planId, backupId, 'pre-backup', 'PRE_BACKUP_START', false);
// Emit backup_init to create the DB entry before dry run.
// This ensures the backup is visible in the DB even if the dry run hangs.
this.emitter.emit('backup_init', {
planId: options.id,
backupId: backupId,
});
// Wait for the 'backup_created' event before proceeding.
await this.waitForBackupCreation(planId, backupId);
// Perform dry run
const dryRunSummary = await this.dryRunBackup(
planId,
backupId,
options,
resticArgsAndEnv,
runConfig
);
// Emit backup_start with dry run summary to update the DB record and send notifications.
this.emitter.emit('backup_start', {
planId: options.id,
backupId: backupId,
summary: dryRunSummary,
});
// Run pre-flight checks
await this.updateProgress(planId, backupId, 'pre-backup', 'PRE_BACKUP_CHECKS_START', false);
await this.canRun(options, resticArgsAndEnv, dryRunSummary);
await this.updateProgress(planId, backupId, 'pre-backup', 'PRE_BACKUP_CHECKS_COMPLETE', true);
// Run pre-backup scripts
await this.updateProgress(planId, backupId, 'pre-backup', 'PRE_BACKUP_SCRIPTS_START', false);
await this.beforeBackup(planId, backupId, options);
await this.updateProgress(planId, backupId, 'pre-backup', 'PRE_BACKUP_SCRIPTS_COMPLETE', true);
// Unlock stale locks
await this.updateProgress(
planId,
backupId,
'pre-backup',
'PRE_BACKUP_UNLOCK_STALE_LOCKS',
false
);
await this.unlockStaleLocks(planId, options, resticArgsAndEnv);
await this.updateProgress(planId, backupId, 'pre-backup', 'PRE_BACKUP_COMPLETE', true);
}
/**
* Execute backup phase - runs the actual restic backup command
*/
protected async executeBackupPhase(
planId: string,
backupId: string,
options: Record<string, any>,
resticArgsAndEnv: ResticArgsAndEnv,
runConfig?: BackupRunConfig
): Promise<string> {
// Update progress: Backup operation start
await this.updateProgress(planId, backupId, 'backup', 'BACKUP_OPERATION_START', false);
const repoPassword = options.settings.encryption ? configService.config.ENCRYPTION_KEY : '';
const baseHandlers = this.createHandlers(planId, backupId);
const { resticArgs, resticEnv } = resticArgsAndEnv;
const resticArgsWithBackupTag: string[] = [...resticArgs, '--tag', `backup-${backupId}`];
const ignoreErrors = runConfig?.ignoreErrors || false;
// Capture restic exit code and warnings
let backupExitCode = 0;
const warnings: string[] = [];
const handlers = {
onProgress: (data: Buffer) => {
this.collectBackupWarnings(data, warnings);
baseHandlers.onProgress(data);
},
onError: baseHandlers.onError,
onComplete: (code: number) => {
backupExitCode = code;
baseHandlers.onComplete(code);
},
};
try {
// Run the Restic Backup command.
const result = await runResticCommand(
resticArgsWithBackupTag,
{ RESTIC_PASSWORD: repoPassword, ...resticEnv },
handlers.onProgress,
handlers.onError,
handlers.onComplete,
process => processManager.trackProcess('backup-' + backupId, process),
{ stallTimeout: RESTIC_STALL_TIMEOUT_MS, timeout: runConfig?.timeout }
);
if (!this.cancelledBackups.has(planId + backupId)) {
// Exit code 3: snapshot created with warnings. Log this as a warning
// in the progress tracking rather than failing/retrying the backup.
if (isResticBackupWarning(backupExitCode)) {
await this.updateProgress(
planId,
backupId,
'backup',
'BACKUP_WARNING',
true,
this.buildBackupWarningMessage(warnings)
);
}
await this.updateProgress(planId, backupId, 'backup', 'BACKUP_OPERATION_COMPLETE', true);
}
return result;
} catch (error: any) {
if (!ignoreErrors) {
const errMsg = error?.message || 'Unknown Error';
await this.updateProgress(
planId,
backupId,
'backup',
'BACKUP_OPERATION_ERROR',
true,
errMsg
);
throw error;
} else {
await this.updateProgress(planId, backupId, 'backup', 'BACKUP_OPERATION_COMPLETE', true);
return '';
}
}
}
/**
* Post-backup phase - cleanup and post-backup operations
*/
private async postBackupPhase(
planId: string,
backupId: string,
options: Record<string, any>,
runConfig?: BackupRunConfig
): Promise<void> {
// Update progress: Post-backup start
await this.updateProgress(planId, backupId, 'post-backup', 'POST_BACKUP_START', false);
// Run post-backup scripts
await this.updateProgress(planId, backupId, 'post-backup', 'POST_BACKUP_SCRIPTS_START', false);
await this.afterBackupSuccess(planId, backupId, options);
await this.updateProgress(
planId,
backupId,
'post-backup',
'POST_BACKUP_SCRIPTS_COMPLETE',
true
);
// Run pruning and stats update
const skipPrune = runConfig?.skipPrune || false;
if (!skipPrune) {
await this.updateProgress(planId, backupId, 'post-backup', 'POST_BACKUP_PRUNE_START', false);
try {
const pruneHandler = new PruneHandler(this.emitter);
await pruneHandler.prune(planId, options);
await this.updateProgress(
planId,
backupId,
'post-backup',
'POST_BACKUP_PRUNE_COMPLETE',
true
);
} catch (error: any) {
const errorMsg = error?.message || 'Unknown Error';
console.warn(
`[BackupHandler]: Failed to prune repository for plan: ${planId}. Error: ${errorMsg}`
);
await this.updateProgress(
planId,
backupId,
'post-backup',
'POST_BACKUP_PRUNE_FAILED',
true,
errorMsg
);
}
}
// Run post-backup repository stats update
await this.updateProgress(
planId,
backupId,
'post-backup',
'POST_BACKUP_REPO_STATS_START',
false
);
try {
// A forced 15 mins timeout is placed as after a huge backup,
// because some remote storage's api rate limit can hang this
const planStats = await getBackupPlanStats(
planId,
options.storage.name,
options.storagePath,
options.settings.encryption,
15 * 60 * 1000
);
this.emitter.emit('backup_stats_update', {
planId,
backupId: backupId,
...(planStats || {}),
});
await this.updateProgress(
planId,
backupId,
'post-backup',
'POST_BACKUP_REPO_STATS_COMPLETE',
true
);
} catch (error: any) {
const errMsg = error?.message || 'Unknown Error';
this.emitter.emit('backup_stats_update', {
planId,
backupId: backupId,
error: errMsg,
});
await this.updateProgress(
planId,
backupId,
'post-backup',
'POST_BACKUP_REPO_STATS_FAILED',
true,
errMsg
);
}
await this.updateProgress(planId, backupId, 'post-backup', 'POST_BACKUP_COMPLETE', true);
}
/**
* Retries failed replication operations for a specific backup.
* Delegates to ReplicationOrchestrator.
*/
async retryFailedReplications(
planId: string,
backupId: string,
options: Record<string, any>,
failedReplicationIds: string[]
): Promise<BackupMirror[]> {
return this.getReplicationOrchestrator().retryFailedReplications(
planId,
backupId,
options,
failedReplicationIds
);
}
/**
* Helper to update backup progress with error handling
*/
protected async updateProgress(
planId: string,
backupId: string,
phase: string,
action: string,
completed: boolean,
error?: string
): Promise<void> {
try {
await this.progressManager.updateAction(planId, backupId, phase, action, completed, error);
} catch (error) {
console.warn(`Warning: Failed to update progress for ${phase}/${action}: ${error}`);
}
}
/**
* A helper method to wait for the 'backup_created' event with a timeout.
* The backup process only continues after the backup entry is created in the database.
* Automatically rejects if the backup_created event is not received after 30 seconds.
*/
private waitForBackupCreation(planId: string, backupId: string): Promise<void> {
return new Promise((resolve, reject) => {
const timeout = setTimeout(() => {
// Clean up the listener to prevent memory leaks.
this.emitter.removeListener('backup_created', onBackupCreated);
reject(
new Error(`Timeout: Did not receive backup_created confirmation for ID: ${backupId}`)
);
}, 30000);
const onBackupCreated = (data: { planId: string; backupId: string }) => {
if (data.backupId === backupId && data.planId === planId) {
clearTimeout(timeout);
this.emitter.removeListener('backup_created', onBackupCreated);
resolve();
}
};
this.emitter.on('backup_created', onBackupCreated);
});
}
/**
* Helper to unlock stale repository locks.
*/
private async unlockStaleLocks(
planId: string,
options: Record<string, any>,
resticArgsAndEnv: ResticArgsAndEnv
): Promise<void> {
if (options.storage && options.storagePath) {
try {
const repoPath = generateResticRepoPath(options.storage.name, options.storagePath || '');
const repoPassword = options.settings.encryption ? configService.config.ENCRYPTION_KEY : '';
await runResticCommand(['unlock', '-r', repoPath], {
...resticArgsAndEnv.resticEnv,
RESTIC_PASSWORD: repoPassword,
});
} catch (error: any) {
console.warn(
`[BackupHandler]: Failed to unlock stale locks for plan: ${planId}. Error: ${error.message}`
);
throw Error(`Failed to unlock stale locks. ${error.message || 'Reason Unknown'}`);
}
}
}
/**
* Checks if the backup can run.
* @param options - Options for the backup process.
* @returns A promise that resolves to a boolean indicating if the backup can run.
*/
async canRun(
options: Record<string, any>,
resticArgsAndEnv: ResticArgsAndEnv,
dryRunSummary?: false | Record<string, any>
): Promise<boolean> {
// Check system resource availability
// Use a fixed minimum (128MB) rather than scaling by CPU count.
// Restic's memory usage doesn't scale linearly with cores, and on macOS
// os.freemem() excludes reclaimable cached memory, making it appear
// much lower than actually available memory.
const availableMemory = os.freemem();
const requiredMemory = 128 * 1024 * 1024; // 128MB minimum
if (availableMemory < requiredMemory) {
throw new Error(`Insufficient memory to perform backup.`);
}
// Check if encryption key is available when encryption is enabled
if (options.settings.encryption && !configService.config.ENCRYPTION_KEY) {
throw new Error(`Encryption enabled but ENCRYPTION_KEY not found.`);
}
// Check if source paths exist and are accessible
if (options.sourceConfig?.includes) {
const pathsNotFound = [];
for (const path of options.sourceConfig.includes) {
try {
// must use stat instead of access since the linux-helper has read capabilities
// through CAP_DAC_READ_SEARCH, which causes access to return false even when the path is readable.
// stat correctly returns the file info without being affected by permissions.
await fs.promises.stat(path);
} catch (error) {
pathsNotFound.push(path);
}
}
if (pathsNotFound.length > 0) {
throw new Error(`Source paths not accessible: ${pathsNotFound.join(', ')}.`);
}
}
// Check the destination has enough free space before the backup starts.
await this.checkBackupDestinationSpace(options, dryRunSummary);
return true;
}
/**
* Checks that the destination volume has enough free space for the backup.
* Throws a non-retryable error if the space is not enough. The skip
* conditions are backup-specific; the measurement is the shared util.
*/
private async checkBackupDestinationSpace(
options: Record<string, any>,
dryRunSummary?: false | Record<string, any>
): Promise<void> {
// Only local storage on the Pluton host is measurable here.
if (options.storage?.type !== 'local') return;
// A remote-device plan would measure the Pluton server, not the device.
if (options.sourceId !== 'main') return;
if (!options.storagePath) return;
// The dry run does not run (rescue method or skipDryRun), so no estimate.
if (!dryRunSummary || dryRunSummary.dry_run_skipped || options.method === 'rescue') return;
const estimated: number = dryRunSummary.data_added_packed || dryRunSummary.data_added || 0;
await checkDestinationSpace({
targetPath: options.storagePath,
estimatedBytes: estimated,
label: 'backup',
});
}
/**
* Cancels the backup process.
* @param planId - The ID of the backup plan.
* @param backupId - The ID of the backup.
* @returns A promise that resolves to a boolean indicating if the backup was cancelled.
*/
async cancel(planId: string, backupId: string): Promise<boolean> {
this.cancelledBackups.add(planId + backupId);
await this.progressManager.markCompleted(
planId,
backupId,
false,
'Backup was cancelled by user',
true
);
try {
const killed = processManager.killProcess('backup-' + backupId);
console.log('[Cancel] killed:', killed);
// Also cancel any running replication processes
if (this.replicationOrchestrator) {
await this.replicationOrchestrator.cancelReplications(backupId);
}
return true;
} catch (error: any) {
console.log('Error Cancelling Backup. ' + error?.message || '');
return false;
}
}
/**
* Creates handlers for the backup process.
* @param planId - The ID of the backup plan.
* @param backupId - The ID of the backup.
* @returns An object containing event handlers for the backup process.
*/
protected createHandlers(planId: string, backupId: string) {
return {
onProgress: (data: Buffer) => {
const progressLine = data.toString().trim();
// Update restic progress in progress file
this.updateResticProgress(planId, backupId, progressLine);
// Also emit the existing event for compatibility
try {
const progressData = JSON.parse(progressLine);
this.emitter.emit('backup_progress', {
planId,
backupId,
data: progressData,
});
} catch (error) {
// Ignore non-JSON lines from restic
}
},
onError: (data: Buffer) => {
this.emitter.emit('backup_error', {
planId,
backupId,
error: data.toString(),
});
},
onComplete: async (code: number) => {
// NOTE: Do NOT emit backup_complete here. The restic process finishes
// before the replication phase, and backup_complete sets inProgress=false
// in the DB, which hides the frontend progress bar prematurely.
// backup_complete is emitted from execute() after the full flow completes.
},
};
}
/**
* Scans a chunk of restic `--json` output for `error` message items and
* accumulates their messages. Used to build the BACKUP_WARNING detail.
*/
protected collectBackupWarnings(data: Buffer, warnings: string[]): void {
// Cap the number of collected warnings so this does not balloon the progress file
const MAX_WARNINGS = 100;
if (warnings.length >= MAX_WARNINGS) return;
const lines = data.toString().split('\n');
for (const line of lines) {
const trimmed = line.trim();
if (!trimmed) continue;
try {
const parsed = JSON.parse(trimmed);
if (parsed?.message_type === 'error') {
const item = parsed.item ? `${parsed.item}: ` : '';
const message = parsed.error?.message || parsed.error || 'Unknown read error';
warnings.push(`${item}${message}`);
if (warnings.length >= MAX_WARNINGS) return;
}
} catch {
// Ignore non-JSON lines.
}
}
}
/**
* Builds a nice warning message for a backup that completed with exit code 3
*/
protected buildBackupWarningMessage(warnings: string[]): string {
const header =
'Backup completed, but some files or directories could not be read and were skipped. The snapshot was still created.';
if (warnings.length === 0) {
return header;
}
return `${header}\n\n${warnings.join('\n')}`;
}
/**
* Helper to update restic progress with error handling
*/
protected async updateResticProgress(
planId: string,
backupId: string,
resticLine: string
): Promise<void> {
try {
await this.progressManager.updateResticProgress(planId, backupId, resticLine);
} catch (error) {
console.warn(`Warning: Failed to update restic progress: ${error}`);
}
}
/**
* Performs a dry run of the backup process.
* @param options - Options for the backup process.
* @returns A promise that resolves to an object containing the result of the dry run.
*/
protected async dryRunBackup(
planId: string,
backupId: string,
options: Record<string, any>,
resticArgsAndEnv: ResticArgsAndEnv,
runConfig?: BackupRunConfig
): Promise<false | Record<string, any>> {
const skip = runConfig?.skipDryRun || false;
const ignoreErrors = runConfig?.ignoreErrors || false;
let dryRunSummary: Record<string, any> = {
message_type: 'summary',
dry_run: true,
dry_run_skipped: true,
files_new: 0,
files_changed: 0,
files_unmodified: 0,
dirs_new: 0,
dirs_changed: 0,
dirs_unmodified: 0,
data_blobs: 0,
tree_blobs: 0,
data_added: 0,
data_added_packed: 0,
total_files_processed: 0,
total_bytes_processed: 0,
total_duration: 0,
snapshot_id: '',
};
if (!skip) {
await this.updateProgress(planId, backupId, 'pre-backup', 'PRE_BACKUP_DRY_RUN_START', false);
const { resticArgs, resticEnv } = resticArgsAndEnv;
const dryRunArgs = [...resticArgs, '--dry-run'];
const dryRunEnv = {
...resticEnv,
RESTIC_PASSWORD: options.settings.encryption ? configService.config.ENCRYPTION_KEY : '',
};
if (options.method === 'rescue') {
dryRunArgs.push('--one-file-system');
}
const handlers = this.createHandlers(planId, backupId);
try {
const dryRunOutput = await runResticCommand(
dryRunArgs,
dryRunEnv,
handlers.onProgress,
handlers.onError,
handlers.onComplete,
undefined,
{ stallTimeout: RESTIC_STALL_TIMEOUT_MS }
);
const outputLines = dryRunOutput.split('\n').filter(line => line.trim() !== '');
const summaryLine = outputLines[outputLines.length - 1];
dryRunSummary = JSON.parse(summaryLine);
await this.updateProgress(
planId,
backupId,
'pre-backup',
'PRE_BACKUP_DRY_RUN_COMPLETE',
true
);
return dryRunSummary;
} catch (error: any) {
if (!ignoreErrors) {
await this.updateProgress(
planId,
backupId,
'pre-backup',
'PRE_BACKUP_DRY_RUN_ERROR',
false,
error?.message || 'Unknown Error'
);
// Preserve the restic exit code
const dryRunError: ResticCommandError = new Error(`Dry run failed: ${error.message}`);
dryRunError.code = (error as ResticCommandError)?.code;
throw dryRunError;
} else {
return dryRunSummary;
}
}
} else {
return dryRunSummary;
}
}
/**
* Creates the arguments for the restic backup command.
* @param planId - The ID of the backup plan.
* @param options - The options for the backup.
* @returns The arguments and the environment variables for the restic backup command.
*/
createResticBackupArgs = (planId: string, options: BackupPlanArgs) => {
const { sourceConfig, storagePath, storage } = options;
const { compression, performance, encryption } = options.settings;
const resticArgs = ['backup'];
const resticEnv: Record<string, string> = {};
if (sourceConfig?.includes) {
sourceConfig.includes.forEach(inPath => {
const pathSlice = inPath.slice(0, 3);
// Handles pattern paths
if (!inPath.startsWith('-')) {
const pathName = pathSlice === 'ip#' ? inPath.replace('ip#', '') : inPath;
resticArgs.push(pathName);
}
});
}
if (sourceConfig?.excludes) {
sourceConfig.excludes.forEach(exPath => {
const pathSlice = exPath.slice(0, 3);
// Handles pattern paths
if (!exPath.startsWith('-')) {
const xpathName = pathSlice === 'ep#' ? exPath.replace('ep#', '') : exPath;
resticArgs.push('--exclude', xpathName);
}
});
}
if (storage.name) {
const repoPath = generateResticRepoPath(storage.name, storagePath || '');
resticArgs.push('-r', repoPath);
}
if (compression) resticArgs.push('--compression', 'auto'); // auto, max, off
if (performance) {
if (performance.maxProcessor) resticEnv.GOMAXPROCS = performance.maxProcessor.toString();
if (performance.packSize) resticArgs.push('--pack-size', performance.packSize);
if (!performance.scan) resticArgs.push('--no-scan');
if (performance.readConcurrency)
resticArgs.push('--read-concurrency', performance.readConcurrency.toString());
if (performance.transfers) {
resticEnv['RCLONE_TRANSFERS'] = performance.transfers.toString();
}
if (performance.bufferSize) {
resticEnv['RCLONE_BUFFER_SIZE'] = performance.bufferSize;
}
if (performance.multiThreadStream) {
resticEnv['RCLONE_MULTI_THREAD_STREAMS'] = performance.multiThreadStream.toString();
}
}
if (!encryption) {
resticArgs.push('--insecure-no-password');
}
resticArgs.push('--tag', 'plan-' + planId);
resticArgs.push('--json');
return { resticArgs, resticEnv };
};
/**
* [PRO] Run user commands before a backup starts.
* This is an extension point for custom backup handling.
*/
protected async beforeBackup(
planId: string,
backupId: string,
options: Record<string, any>
): Promise<void> {
await this.runScripts('onBackupStart', planId, backupId, options);
}
/**
* Run user commands after a backup ends. Run on both success and error.
* This is an extension point for custom backup handling.
*/
protected async afterBackup(
planId: string,
backupId: string,
options: Record<string, any>
): Promise<void> {
await this.runScripts('onBackupEnd', planId, backupId, options);
}
/**
* Run user commands after a backup completes successfully.
* This is an extension point for custom backup handling.
*/
protected async afterBackupSuccess(
planId: string,
backupId: string,
options: Record<string, any>
): Promise<void> {
await this.runScripts('onBackupComplete', planId, backupId, options);
}
/**
* Overrides the core 'afterBackupSuccess' hook to run user commands.
* This is an extension point for custom backup handling.
*/
protected async afterBackupError(
planId: string,
backupId: string,
options: Record<string, any>
): Promise<void> {
await this.runScripts('onBackupError', planId, backupId, options);
}
/**
* Run user commands after a backup fails permanently.
* This is an extension point for custom backup handling.
*/
protected async afterBackupFailure(
planId: string,
backupId: string,
options: Record<string, any>
): Promise<void> {
await this.runScripts('onBackupFailure', planId, backupId, options);
}
protected async runScripts(
eventName: string,
planId: string,
backupId: string,
options: Record<string, any>
) {
const phase = this.getPhaseFromScriptEvent(eventName);
const scripts = options?.settings?.scripts?.[eventName] || [];
await runScriptsForEvent(
eventName,
scripts,
async scriptName => {
await this.updateProgress(planId, backupId, phase, scriptName + '_START', false);
},
async scriptName => {
await this.updateProgress(planId, backupId, phase, scriptName + '_COMPLETE', true);
},
async (scriptName, message) => {
await this.updateProgress(planId, backupId, phase, scriptName + '_FAIL', true, message);
}
);
}
protected getPhaseFromScriptEvent(eventName: string): string {
let phase = 'post-backup';
if (eventName === 'onBackupStart') {
phase = 'pre-backup';
}
return phase;
}
}