sync15/clients_engine/
mod.rs

Help
1/* This Source Code Form is subject to the terms of the Mozilla Public
2 * License, v. 2.0. If a copy of the MPL was not distributed with this
3 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
4
5//! The client engine is a [crate::engine](Sync Engine) used to manage the
6//! "clients" collection. The clients engine manages the client record for
7//! "this device, and also manages "commands".
8//! In short, commands target one or more engines and instruct them to
9//! perform various operations - such as wiping all local data.
10//! These commands are used very rarely - currently the only command used
11//! in practice is for bookmarks to wipe all their data, which is sent when
12//! a desktop device restores all bookmarks from a backup. In this scenario,
13//! desktop will delete all local bookmarks then replace them with the backed
14//! up set, which without a "wipe" command would almost certainly cause other
15//! connected devices to "resurrect" the deleted bookmarks.
16use std::collections::HashSet;
17
18mod engine;
19mod record;
20mod ser;
21
22use crate::DeviceType;
23use anyhow::Result;
24pub use engine::Engine;
25
26// These are what desktop uses.
27const CLIENTS_TTL: u32 = 15_552_000; // 180 days
28pub(crate) const CLIENTS_TTL_REFRESH: u64 = 604_800; // 7 days
29
30/// A command processor applies incoming commands like wipes and resets for all
31/// stores, and returns commands to send to other clients. It also manages
32/// settings like the device name and type, which is stored in the special
33/// `clients` collection.
34///
35/// In practice, this trait only has one implementation, in the sync manager.
36/// It's split this way because the clients engine depends on internal `sync15`
37/// structures, and can't be implemented as a syncable store...but `sync15`
38/// doesn't know anything about multiple engines. This lets the sync manager
39/// provide its own implementation for handling wipe and reset commands for all
40/// the engines that it manages.
41pub trait CommandProcessor {
42    fn settings(&self) -> &Settings;
43
44    /// Fetches commands to send to other clients. An error return value means
45    /// commands couldn't be fetched, and halts the sync.
46    fn fetch_outgoing_commands(&self) -> Result<HashSet<Command>>;
47
48    /// Applies a command sent to this client from another client. This method
49    /// should return a `CommandStatus` indicating whether the command was
50    /// processed.
51    ///
52    /// An error return value means the sync manager encountered an error
53    /// applying the command, and halts the sync to prevent unexpected behavior
54    /// (for example, merging local and remote bookmarks, when we were told to
55    /// wipe our local bookmarks).
56    fn apply_incoming_command(&self, command: Command) -> Result<CommandStatus>;
57}
58
59/// Indicates if a command was applied successfully, ignored, or not supported.
60/// Applied and ignored commands are removed from our client record, and never
61/// retried. Unsupported commands are put back into our record, and retried on
62/// subsequent syncs. This is to handle clients adding support for new data
63/// types.
64#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
65pub enum CommandStatus {
66    Applied,
67    Ignored,
68    Unsupported,
69}
70
71/// Information about this device to include in its client record. This should
72/// be persisted across syncs, as part of the sync manager state.
73#[derive(Clone, Debug, Eq, Hash, PartialEq)]
74pub struct Settings {
75    /// The FxA device ID of this client, also used as this client's record ID
76    /// in the clients collection.
77    pub fxa_device_id: String,
78    /// The name of this client. This should match the client's name in the
79    /// FxA device manager.
80    pub device_name: String,
81    /// The type of this client: mobile, tablet, desktop, or other.
82    pub device_type: DeviceType,
83}
84
85#[derive(Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
86pub enum Command {
87    /// Erases all local data for a specific engine.
88    Wipe(String),
89    /// Resets local sync state for all engines.
90    ResetAll,
91    /// Resets local sync state for a specific engine.
92    Reset(String),
93}
sync15/clients_engine/mod.rs

sync15/clients_engine/
mod.rs
