Backup Resources Reference

A BackupResource is the base class used to represent a group of data within a user profile that is logical to backup together. For example, the PlacesBackupResource represents both the places.sqlite SQLite database, as well as the favicons.sqlite database. The AddonsBackupResource represents not only the preferences for various addons, but also the XPI files that those addons are defined in.

Each BackupResource subclass is registered for use by the BackupService by adding it to the default set of exported classes in the BackupResources module in BackupResources.sys.mjs.

class BackupResource()

An abstract class representing a set of data within a user profile that can be persisted to a separate backup archive file, and restored to a new user profile from that backup archive file.

BackupResource.BackupResource

BackupResource.key

type: string

This must be overridden to return a simple string identifier for the resource, for example “places” or “extensions”. This key is used as a unique identifier for the resource.

BackupResource.priority

This can be overridden to return a number indicating the priority the resource should have in the backup order.

Resources with a higher priority will be backed up first. The default priority of 0 indicates it can be processed in any order.

BackupResource.requiresEncryption

type: boolean

This must be overridden to return a boolean indicating whether the resource requires encryption when being backed up. Encryption should be required for particularly sensitive data, such as passwords / credentials, cookies, or payment methods. If you’re not sure, talk to someone from the Privacy team.

BackupResource.backup(stagingPath, profilePath="null")

Perform a safe copy of the datastores that this resource manages and write them into the backup database. The Promise should resolve with an object that can be serialized to JSON, as it will be written to the manifest file. This same object will be deserialized and passed to restore() when restoring the backup. This object can be null if no additional information is needed to restore the backup.

Arguments:

• stagingPath (string) – The path to the staging folder where copies of the datastores for this BackupResource should be written to.

• profilePath (string) – This is null if the backup is being run on the currently running user profile. If, however, the backup is being run on a different user profile (for example, it’s being run from a BackgroundTask on a user profile that just shut down, or during test), then this is a string set to that user profile path.

Returns:

Promise.<(object|null)> –

BackupResource.measure(profilePath)

This must be overridden to record telemetry on the size of any data associated with this BackupResource.

Arguments:

• profilePath (string) – path to a profile directory.

Returns:

Promise.<undefined> –

BackupResource.postRecovery(postRecoveryEntry)

Perform any post-recovery operations that need to be done after the recovery has been completed and the recovered profile has been attached to.

This method is running in an app connected to the recovered profile. The profile is locked, but this postRecovery method can be used to insert data into connected datastores, or perform any other operations that can only occur within the context of the recovered profile.

Arguments:

• postRecoveryEntry (object|null) – The object that was returned by the recover() method when the recovery was originally done. This object can be null if no additional information is needed for post-recovery.

See also

• BackupResource.recover()

BackupResource.recover(manifestEntry, recoveryPath, destProfilePath)

Recovers the datastores that this resource manages from a backup archive that has been decompressed into the recoveryPath. A pre-existing unlocked user profile should be available to restore into, and destProfilePath should point at its location on the file system.

This method is not expected to be running in an app connected to the destProfilePath. If the BackupResource needs to run some operations while attached to the recovery profile, it should do that work inside of postRecovery(). If data needs to be transferred to postRecovery(), it should be passed as a JSON serializable object in the return value of this method.

Arguments:

• manifestEntry (object|null) – The object that was returned by the backup() method when the backup was created. This object can be null if no additional information was needed for recovery.

• recoveryPath (string) – The path to the resource directory where the backup archive has been decompressed.

• destProfilePath (string) – The path to the profile directory where the backup should be restored to.

Returns:

Promise.<(object|null)> – This should return a JSON serializable object that will be passed to postRecovery() if any data needs to be passed to it. This object can be null if no additional information is needed for postRecovery().

See also

• BackupResource.postRecovery()

static BackupResource.copyFiles(sourcePath, destPath, fileNames)

A helper function to copy a set of files from a source directory to a destination directory. Callers should ensure that the source files can be copied safely before invoking this function. Files that do not exist will be ignored. Callers that wish to copy SQLite databases should use copySqliteDatabases() instead.

Arguments:

• sourcePath (string) – Path to the source directory of the files to be copied.

• destPath (string) – Path to the destination directory where the files should be copied to.

• fileNames (Array.<string>) – An array of filenames of the files to copy.

Returns:

Promise.<undefined> –

static BackupResource.copySqliteDatabases(sourcePath, destPath, sqliteDatabases)

Copy a set of SQLite databases safely from a source directory to a destination directory. A new read-only connection is opened for each database, and then a backup is created. If the source database does not exist, it is ignored.

Arguments:

• sourcePath (string) – Path to the source directory of the SQLite databases.

• destPath (string) – Path to the destination directory where the SQLite databases should be copied to.

• sqliteDatabases (Array.<string>) – An array of filenames of the SQLite databases to copy.

Returns:

Promise.<undefined> –

static BackupResource.getDirectorySize(directoryPath, options)

Get the total size of a directory.

Arguments:

• directoryPath (string) – path to a directory.

• options (object) – A set of additional optional parameters.

• options.shouldExclude (function) – an optional callback which based on file path and file type should return true if the file should be excluded from the computed directory size.

Returns:

Promise.<(number|null)> – - the size of all descendants of the directory in kilobytes, or null if the directory does not exist, the path is not a directory or the size is unknown.

static BackupResource.getFileSize(filePath)

Get the size of a file.

Arguments:

• filePath (string) – path to a file.

Returns:

Promise.<(number|null)> – - the size of the file in kilobytes, or null if the file does not exist, the path is a directory or the size is unknown.