Backup Service Reference

class BackupService(backupResources=DefaultBackupResources)

The BackupService class orchestrates the scheduling and creation of profile backups. It also does most of the heavy lifting for the restoration of a profile backup.

Create a BackupService instance.

Arguments:

  • backupResources (object) – Object containing BackupResource classes to associate with this service.

BackupService.BackupService

Create a BackupService instance.

BackupService.backupInProgress

type: boolean

True if a backup is currently in progress.

BackupService.instance

type: BackupService|null

The BackupService singleton instance.

BackupService.manifestSchemaPromise

type: Promise.<object>

A promise that resolves to the schema for the backup manifest that this BackupService uses when creating a backup. This should be accessed via the MANIFEST_SCHEMA static getter.

BackupService.resources

type: Map.<string, BackupResource>

Map of instantiated BackupResource classes.

BackupService.MANIFEST_FILE_NAME

type: string

The name of the backup manifest file.

BackupService.MANIFEST_SCHEMA

type: Promise.<object>

The current schema version of the backup manifest that this BackupService uses when creating a backup.

BackupService.MANIFEST_SCHEMA_VERSION

type: number

The current schema version of the backup manifest that this BackupService uses when creating a backup.

BackupService.POST_RECOVERY_FILE_NAME

type: string

The name of the post recovery file written into the newly created profile directory just after a profile is recovered from a backup.

BackupService.checkForPostRecovery(profilePath="PathUtils.profileDir")

Checks for the POST_RECOVERY_FILE_NAME in the current profile directory. If one exists, instantiates any relevant BackupResource’s, and calls postRecovery() on them with the appropriate entry from the file. Once this is done, deletes the file.

The file is deleted even if one of the postRecovery() steps rejects or fails.

This function resolves silently if the POST_RECOVERY_FILE_NAME file does not exist, which should be the majority of cases.

Arguments:

  • profilePath (string) – The profile path to look for the POST_RECOVERY_FILE_NAME file. Defaults to the current profile.

Returns:

Promise.<undefined> –

BackupService.createBackup(options)

Create a backup of the user’s profile.

Arguments:

  • options (object) – Options for the backup.

  • options.profilePath (string) – The path to the profile to backup. By default, this is the current profile.

Returns:

Promise.<(CreateBackupResult|null)> – A promise that resolves to an object containing the path to the staging folder where the backup was created, or null if the backup failed.

BackupService.recoverFromBackup(recoveryPath, shouldLaunch=false, profileRootPath="null")

Given a decompressed backup archive at recoveryPath, this method does the following:

  1. Reads in the backup manifest from the archive and ensures that it is valid.

  2. Creates a new named profile directory using the same name as the one found in the backup manifest, but with a different prefix.

  3. Iterates over each resource in the manifest and calls the recover() method on each found BackupResource, passing in the associated ManifestEntry from the backup manifest, and collects any post-recovery data from those resources.

  4. Writes a post-recovery.json file into the newly created profile directory.

  5. Returns the name of the newly created profile directory.

Arguments:

  • recoveryPath (string) – The path to the decompressed backup archive on the file system.

  • shouldLaunch (boolean) – An optional argument that specifies whether an instance of the app should be launched with the newly recovered profile after recovery is complete.

  • profileRootPath (string) – An optional argument that specifies the root directory where the new profile directory should be created. If not provided, the default profile root directory will be used. This is primarily meant for testing.

Throws:

Exception – In the event that recovery somehow failed.

Returns:

Promise.<nsIToolkitProfile> – The nsIToolkitProfile that was created for the recovered profile.

BackupService.takeMeasurements()

Take measurements of the current profile state for Telemetry.

Returns:

Promise.<undefined> –

static BackupService._getSchemaForVersion(version)

Returns the schema for the backup manifest for a given version.

This should really be #getSchemaForVersion, but for some reason, sphinx-js seems to choke on static async private methods (bug 1893362). We workaround this breakage by using the _ prefix to indicate that this method should be _considered_ private, and ask that you not use this method outside of this class. The sphinx-js issue is tracked at https://github.com/mozilla/sphinx-js/issues/240.

Arguments:

  • version (number) – The version of the schema to return.

Returns:

Promise.<object> –

static BackupService.get()

Returns a reference to the BackupService singleton. If the singleton has not been initialized, an error is thrown.

Returns:

BackupService –

static BackupService.init()

Returns a reference to a BackupService singleton. If this is the first time that this getter is accessed, this causes the BackupService singleton to be be instantiated.