Revision control
Copy as Markdown
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
[External="sync15"]
typedef extern DeviceType;
namespace syncmanager { };
[Error]
enum SyncManagerError {
"UnknownEngine",
"UnsupportedFeature",
"Sync15Error",
"UrlParseError",
"InterruptedError",
"JsonError",
"LoginsError",
"PlacesError",
"AnyhowError",
};
dictionary SyncParams {
/// Why are we performing this sync?
SyncReason reason;
/// Which engines should we sync?
SyncEngineSelection engines;
/// Which engines should be enabled in the "account global" list (for
/// example, if the UI was used to change an engine's state since the last
/// sync).
record<DOMString, boolean> enabled_changes;
/// Keys to encrypt/decrypt data from local database files. These are
/// separate from the key we use to encrypt the sync payload as a whole.
record<DOMString, string> local_encryption_keys;
/// Authorization for the sync server
SyncAuthInfo auth_info;
/// An opaque string, as returned in the previous sync's SyncResult and
/// persisted to disk, or null if no such state is available. This includes
/// information such as the list of engines previously enabled, certain
/// server timestamps and GUIDs etc. If this value isn't correctly persisted
/// and round-tripped, each sync may look like a "first sync".
string? persisted_state;
/// Information about the current device, such as its name, formfactor and
/// FxA device ID.
DeviceSettings device_settings;
};
[Enum]
interface SyncEngineSelection {
All();
Some(sequence<string> engines);
};
enum SyncReason {
"Scheduled",
"User",
"PreSleep",
"Startup",
"EnabledChange",
"Backgrounded",
};
dictionary SyncAuthInfo {
string kid;
string fxa_access_token;
string sync_key;
string tokenserver_url;
};
dictionary DeviceSettings {
string fxa_device_id;
string name;
DeviceType kind;
};
dictionary SyncResult {
/// Result from the sync server
ServiceStatus status;
/// Engines that synced successfully
sequence<string> successful;
/// Maps the names of engines that failed to sync to the reason why
record<DOMString, string> failures;
/// State that should be persisted to disk and supplied to the sync method
/// on the next sync (See SyncParams.persisted_state).
string persisted_state;
/// The list of engines which are marked as "declined" (ie, disabled) on the
/// sync server. The list of declined engines is global to the account
/// rather than to the device. Apps should use this after every sync to
/// update the local state (ie, to ensure that their Sync UI correctly
/// reflects what engines are enabled and disabled), because these could
/// change after every sync.
sequence<string>? declined;
/// Earliest time that the next sync should happen at
timestamp? next_sync_allowed_at;
/// JSON string encoding a `SyncTelemetryPing` object
string? telemetry_json;
};
enum ServiceStatus {
"Ok",
"NetworkError",
"ServiceError",
"AuthError",
"BackedOff",
"OtherError",
};
interface SyncManager {
constructor();
/// Disconnect engines from sync, deleting/resetting the sync-related data
void disconnect();
/// Perform a sync. See [SyncParams] and [SyncResult] for details on how this works
[Throws=SyncManagerError]
SyncResult sync(SyncParams params);
/// Get a list of engine names available for syncing
sequence<string> get_available_engines();
};