architecture.rst (5767B)
1 High-level architecture 2 ======================= 3 4 The ``BackupService`` module is architected in a way to make testing its 5 individual components relatively easy with unit tests. 6 7 The main entry point exists in a module called 8 ``BackupService.sys.mjs``, which is `invoked and initialized via in the 9 BrowserGlue idle tasks 10 list <https://searchfox.org/mozilla-central/rev/97feebcab27f1a92e70ceacaa77211e9eaba0e6e/browser/components/BrowserGlue.sys.mjs#2449-2470>`__ 11 12 The ``BackupService`` manages two high-level operations: creation of 13 backups, and recovery from such backups. 14 15 BackupService diagram 16 --------------------- 17 18 This is a non-exhaustive architecture diagram that attempts to 19 illustrate the relationships between various high-level components 20 surrounding ``BackupService``. 21 22 .. image:: architecture.svg 23 24 This set of components surrounding ``BackupService`` is fairly self 25 contained, and there are very few points outside of 26 ``browser/components/backup`` where the ``BackupService`` or any of 27 these other components are used. The exceptions here being 28 ``BrowserGlue`` to kick off initialization, and the preferences UI which 29 embeds wigetry to control the ``BackupService``. 30 31 Creating backups 32 ---------------- 33 34 ``BackupService`` initialization takes the opportunity to collect some 35 Telemetry, and after sets up a scheduling mechanism to generate backups 36 if the user has configured it to. 37 38 The process of creating a backup has three stages: 39 40 1. Copying the resources into a temporary staging folder 41 2. Creating the archive file 42 3. Cleanup 43 44 Copying the resources into a temporary staging folder 45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 46 47 The ``BackupService`` create (or overwrite if pre-existing) a folder at 48 ``ProfD/backups/staging``. For each ``BackupResource``, a folder will be 49 created under that ``staging`` folder. The path to that folder will then 50 be passed to each ``BackupResource``, which will then be responsible for 51 safely copying the datastores that the ``BackupResource`` represents 52 into the new folder. ``BackupResource``\ s may also perform 53 pre-processing on these copies before they’re written. 54 55 Note: Some ``BackupResource`` subclasses only have ``backup`` called if 56 the user has configured backups to be encrypted. This is because we want 57 to do our best to protect a backup file that may be sent over untrusted 58 channels - for example, uploaded over the network to Dropbox or Google 59 Drive, or even sent through email. The most sensitive data (passwords, 60 cookies and payment methods) are only included in the backup when 61 encryption is enabled. 62 63 For JSON or binary files that are atomically written to, simple file 64 copy operations are used by each ``BackupResource``. For SQLite 65 databases, the `SQLite Online Backup 66 API <https://www.sqlite.org/backup.html>`__ is used to ensure a complete 67 working copy is made. This API is made available through 68 ``Sqlite.sys.mjs``. 69 70 A ``backup-manifest.json`` file is also included in the ``staging`` 71 folder, describing the resources stored, and other metadata about the 72 created backup. 73 74 Creating the single-file archive 75 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 76 77 Once all ``BackupResource``\ s have had a chance to make their copies, 78 the contents of the ``staging`` folder is compressed and packaged into a 79 single-file archive. This archive may be encrypted if the user has 80 configured backups to include sensitive data. 81 82 Cleaning up 83 ~~~~~~~~~~~ 84 85 Once the single-file archive has been created, it is moved into the 86 user-configured location, overwriting any pre-existing backup file for 87 the particular profile. 88 89 Having done that, the ``backups/staging`` folder is then deleted. 90 91 Recovering from backups 92 ----------------------- 93 94 The process of recovering from a backup has three stages: 95 96 1. Extraction and decompression from the single-file archive 97 2. Recovering into a newly created profile folder 98 3. Post-recovery actions 99 100 Extraction 101 ~~~~~~~~~~ 102 103 The first step is to extract (and if encrypted, to decrypt) the backed 104 up data from the single-file archive. The end-result of this step is a 105 new folder being created under ``ProfD/backups/recovery`` that has the 106 backup contents decompressed into it. The ``recovery`` folder is an 107 exact mirror of the ``staging`` folder for when the backup was created. 108 109 Recovering into a newly created profile folder 110 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 111 112 The ``BackupService`` will create a new user profile, and then for each 113 resource listed in ``backup-manifest.json``, the associated 114 ``BackupResource`` will be instantiated and passed the path to the 115 subfolder under ``recovery`` associated with the ``resource``. The 116 ``BackupResource`` is then responsible for copying the datastores from 117 that folder into the newly created profile folder. 118 119 Each ``BackupResource``, while recovering, may emit some information 120 that gets written to a ``post-recovery.json`` file that is also written 121 into the profile folder. 122 123 Once this completes, the newly created profile is launched and the 124 current one shut down. 125 126 Post-recovery 127 ~~~~~~~~~~~~~ 128 129 ``BackupService`` initialization also checks to see if the launched 130 profile was just recovered from a backup, in which case, post-recovery 131 actions may occur - for example, datastore updates that can only occur 132 when the recovered profile is running. 133 134 This is done by checking for the ``post-recovery.json`` file in the 135 current profile directory. If this is found, then each 136 ``BackupResource`` is instantiated and passed the post-recovery data 137 that was emitted and stored in the JSON file during recovery. 138 139 This is useful when there are certain actions that can only be performed 140 when the recovered profile is running. For example, we can only insert 141 data into IndexedDB databases within an application that is attached to 142 those databases.