sousa-gecko/third_party/application-services/components/sync_manager/src/syncmanager.udl

/* 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
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

[External="sync15"]
typedef enum 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();
};