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();
};