|
| 1 | +# Frequently Asked Questions |
| 2 | + |
| 3 | +## What is Sync? |
| 4 | + |
| 5 | +Sync is a system of both a backend and client engines that are responsible for the syncing of client data to the storage server. |
| 6 | + |
| 7 | +## When do things sync? |
| 8 | + |
| 9 | +Engines do a full sync on a regular period (except for Tabs, see below): |
| 10 | + |
| 11 | +- **iOS**: Every 15 minutes |
| 12 | +- **Fenix**: Every 4 hours (after an initial delay) |
| 13 | +- **Desktop**: |
| 14 | + - Initial delay: |
| 15 | + - Wake from sleep: 2s after wake |
| 16 | + - After startup: 5 minutes |
| 17 | + - The period varies depending on state: |
| 18 | + - Idle: 1 hour |
| 19 | + - Active: 10 minutes |
| 20 | + - After recently syncing something: 1.5 minutes (if we've synced something new, we temporarily change the sync delay from 10min → 1.5min until we don't have anything left to sync) |
| 21 | + |
| 22 | +**Tabs** were changed with MR 2022 to sync every 5s after a tab change. This is sometimes called "quick writing." |
| 23 | + |
| 24 | +## In what order do things sync? |
| 25 | + |
| 26 | +The order of the engines is determined per-platform. |
| 27 | + |
| 28 | +- **Desktop**: engines, prefs, passwords, tabs, bookmarks, addons, form autofill, forms, history, extension storage |
| 29 | +- **Mobile**: Matches desktop, ignoring engines and prefs as they aren't analogous |
| 30 | + |
| 31 | +However, clients can override this. |
| 32 | + |
| 33 | +## What happens when I click on "Sync Now" in Firefox? |
| 34 | + |
| 35 | +A "Sync Now" button or link in the UI on device A only initiates syncing for that same device A – it does not force all of your connected devices to sync. This is still true when "Sync now" is a contextual option (such as the Firefox sidebar) – clicking on what appears to be "Sync now" for a connected mobile device from desktop actually only initiates syncing of that desktop. |
| 36 | + |
| 37 | +## Does every platform have its own engines? |
| 38 | + |
| 39 | +We use shared components as much as possible to avoid every platform having its own engines. |
| 40 | + |
| 41 | +## Can Mozilla read/inspect/decrypt a user's synced data? |
| 42 | + |
| 43 | +No. Client data is encrypted before it leaves the client; we cannot decrypt this outside of the client, by design. Therefore, the server is extremely limited (e.g. no searching, filtering, fancy queries, etc). If you want to do operations on the data, they have to be done on the client. |
| 44 | + |
| 45 | +## What is the structure of synced data on the storage server? |
| 46 | + |
| 47 | +The structure of the synced data is not the same as the structure of the data in the client. You don't sync entire databases. Synced data is a set of JSON key-value stores with no relationships between them. |
| 48 | + |
| 49 | +- In these key-value stores, the key is a GUID and the value is an encrypted blob of JSON. Each of these stores represents a "collection" (bookmarks, tabs, logins, etc). |
| 50 | +- The JSON blobs are associated with hashed user and key IDs derived from the user's FxA. There are no identifiable relationships of this data apart from the `collection_id` foreign key that identifies what type of data it is. |
| 51 | +- In most cases, each item in a store is its own record (e.g. each bookmark is one record). Tabs is different, as each device's tabs is in a single record. |
| 52 | +- Because the JSON blob is encrypted, the server cannot see the content of any synced data. This means: |
| 53 | + - No relationships are enforced between collections |
| 54 | + - No atomic updates are possible across collections, only within a collection |
| 55 | + - Modeling a relational DB in synced data isn't viable |
| 56 | + |
| 57 | +## Where are the user's Sync settings stored? |
| 58 | + |
| 59 | +The storage server does not store the user's Sync settings, and neither does FxA. When a user sets which types of data to sync, those are sent to the storage server as collections that the indicated user will sync. Subsequent syncs will request to this data as part of the sync process. |
| 60 | + |
| 61 | +## Syncing, step by step |
| 62 | + |
| 63 | +From the client/user perspective: |
| 64 | + |
| 65 | +1. Fetch kSync encryption key and kXCS node assignment token from FxA |
| 66 | +2. Obtain token and storage node endpoint from token server |
| 67 | +3. Fetch (unencrypted) associated collections (`info/collections`) and their last-modified time |
| 68 | +4. Fetch (unencrypted) global metadata (`meta/global`) about syncing – IDs, version numbers, etc |
| 69 | +5. Compare global sync IDs and storage versions to determine if we can sync – or if we need to start over |
| 70 | +6. Fetch encryption and signing keys (`crypto/keys`) for future syncing |
| 71 | +7. Sync the clients engine to download new client records and commands |
| 72 | +8. Process incoming client commands |
| 73 | +9. Determine and update enabled engines |
| 74 | +10. For each enabled engine: |
| 75 | + - Fetch new records from the server |
| 76 | + - Decrypt each record and handle decryption errors |
| 77 | + - Resolve merge conflicts between incoming and changed records from step 10 |
| 78 | + - Insert and update new records into the local store |
| 79 | + - Ask the tracker for a list of IDs changed since the last sync, and upload these records to the server |
| 80 | + - If an engine tracks a "backlog", make some progress on that backlog. This is only true for the history engine on desktop |
| 81 | +11. Sync the clients engine to upload outgoing commands |
| 82 | +12. Update `meta/global` on the server |
| 83 | +13. Run validation for synced engines |
| 84 | +14. Schedule next sync |
0 commit comments