components/sync/protocol/sync.proto

// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
//
// Sync protocol for communication between sync client and server.

// If you change or add any fields in this file, update proto_visitors.h and
// potentially proto_enum_conversions.{h, cc}. If you add new Specifics proto,
// also update proto_value_conversions.{h, cc}.

syntax = "proto2";

option java_multiple_files = true;
option java_package = "org.chromium.components.sync.protocol";

option optimize_for = LITE_RUNTIME;

package sync_pb;

import "components/sync/protocol/app_list_specifics.proto";
import "components/sync/protocol/app_notification_specifics.proto";
import "components/sync/protocol/app_setting_specifics.proto";
import "components/sync/protocol/app_specifics.proto";
import "components/sync/protocol/arc_package_specifics.proto";
import "components/sync/protocol/autofill_specifics.proto";
import "components/sync/protocol/autofill_offer_specifics.proto";
import "components/sync/protocol/bookmark_specifics.proto";
import "components/sync/protocol/client_commands.proto";
import "components/sync/protocol/client_debug_info.proto";
import "components/sync/protocol/data_type_progress_marker.proto";
import "components/sync/protocol/device_info_specifics.proto";
import "components/sync/protocol/dictionary_specifics.proto";
import "components/sync/protocol/encryption.proto";
import "components/sync/protocol/experiments_specifics.proto";
import "components/sync/protocol/extension_setting_specifics.proto";
import "components/sync/protocol/extension_specifics.proto";
import "components/sync/protocol/favicon_image_specifics.proto";
import "components/sync/protocol/favicon_tracking_specifics.proto";
import "components/sync/protocol/get_updates_caller_info.proto";
import "components/sync/protocol/history_delete_directive_specifics.proto";
import "components/sync/protocol/managed_user_setting_specifics.proto";
import "components/sync/protocol/managed_user_shared_setting_specifics.proto";
import "components/sync/protocol/managed_user_specifics.proto";
import "components/sync/protocol/nigori_specifics.proto";
import "components/sync/protocol/os_preference_specifics.proto";
import "components/sync/protocol/os_priority_preference_specifics.proto";
import "components/sync/protocol/password_specifics.proto";
import "components/sync/protocol/preference_specifics.proto";
import "components/sync/protocol/printer_specifics.proto";
import "components/sync/protocol/priority_preference_specifics.proto";
import "components/sync/protocol/reading_list_specifics.proto";
import "components/sync/protocol/search_engine_specifics.proto";
import "components/sync/protocol/security_event_specifics.proto";
import "components/sync/protocol/send_tab_to_self_specifics.proto";
import "components/sync/protocol/session_specifics.proto";
import "components/sync/protocol/sharing_message_specifics.proto";
import "components/sync/protocol/sync_enums.proto";
import "components/sync/protocol/synced_notification_app_info_specifics.proto";
import "components/sync/protocol/synced_notification_specifics.proto";
import "components/sync/protocol/theme_specifics.proto";
import "components/sync/protocol/typed_url_specifics.proto";
import "components/sync/protocol/unique_position.proto";
import "components/sync/protocol/user_consent_specifics.proto";
import "components/sync/protocol/user_event_specifics.proto";
import "components/sync/protocol/web_app_specifics.proto";
import "components/sync/protocol/webauthn_credential_specifics.proto";
import "components/sync/protocol/wifi_configuration_specifics.proto";
import "components/sync/protocol/workspace_desk_specifics.proto";

// Used for inspecting how long we spent performing operations in different
// backends. All times must be in millis.
message ProfilingData {
  optional int64 meta_data_write_time = 1;
  optional int64 file_data_write_time = 2;
  optional int64 user_lookup_time = 3;
  optional int64 meta_data_read_time = 4;
  optional int64 file_data_read_time = 5;
  optional int64 total_request_time = 6;
}

message EntitySpecifics {
  // If a datatype is encrypted, this field will contain the encrypted
  // original EntitySpecifics. The extension for the datatype will continue
  // to exist, but contain only the default values.
  // Note that currently passwords employ their own legacy encryption scheme and
  // do not use this field.
  optional EncryptedData encrypted = 1;

  // To add new datatype-specific fields to the protocol, extend
  // EntitySpecifics.  First, pick a non-colliding tag number by
  // picking a Cr-Commit-Position of one of your past commits
  // to src.chromium.org.  Then, in a different protocol buffer
  // definition, define your message type, and add an optional field
  // to the list below using the unique tag value you selected.
  //
  //  optional MyDatatypeSpecifics my_datatype = 32222;
  //
  // where:
  //   - 32222 is the non-colliding tag number you picked earlier.
  //   - MyDatatypeSpecifics is the type (probably a message type defined
  //     in your new .proto file) that you want to associate with each
  //     object of the new datatype.
  //   - my_datatype is the field identifier you'll use to access the
  //     datatype specifics from the code.
  //
  // Server implementations are obligated to preserve the contents of
  // EntitySpecifics when it contains unrecognized fields.  In this
  // way, it is possible to add new datatype fields without having
  // to update the server.
  //
  // Note: The tag selection process is based on legacy versions of the
  // protocol which used protobuf extensions. We have kept the process
  // consistent as the old values cannot change.  The 5+ digit nature of the
  // tags also makes them recognizable (individually and collectively) from
  // noise in logs and debugging contexts, and creating a divergent subset of
  // tags would only make things a bit more confusing.

  oneof specifics_variant {
    AutofillSpecifics autofill = 31729;
    BookmarkSpecifics bookmark = 32904;
    PreferenceSpecifics preference = 37702;
    TypedUrlSpecifics typed_url = 40781;
    ThemeSpecifics theme = 41210;
    // TODO(crbug.com/1012648): |app_notification| isn't used by the client
    // anymore, but the server still needs it for now.
    AppNotification app_notification = 45184 [deprecated = true];
    PasswordSpecifics password = 45873;
    NigoriSpecifics nigori = 47745;
    ExtensionSpecifics extension = 48119;
    AppSpecifics app = 48364;
    SessionSpecifics session = 50119;
    AutofillProfileSpecifics autofill_profile = 63951;
    SearchEngineSpecifics search_engine = 88610;
    ExtensionSettingSpecifics extension_setting = 96159;
    AppSettingSpecifics app_setting = 103656;
    HistoryDeleteDirectiveSpecifics history_delete_directive = 150251;
    // TODO(crbug.com/1012648): |synced_notification| and
    // |synced_notification_app_info| aren't used by the client anymore, but the
    // server still needs them for now.
    SyncedNotificationSpecifics synced_notification = 153108
        [deprecated = true];
    SyncedNotificationAppInfoSpecifics synced_notification_app_info = 235816
        [deprecated = true];
    DeviceInfoSpecifics device_info = 154522;
    // TODO(crbug.com/1009361): |experiments| isn't used by the client anymore,
    // but the server still needs it for now.
    ExperimentsSpecifics experiments = 161496 [deprecated = true];
    PriorityPreferenceSpecifics priority_preference = 163425;
    DictionarySpecifics dictionary = 170540;
    FaviconTrackingSpecifics favicon_tracking = 181534
        [deprecated = true];
    FaviconImageSpecifics favicon_image = 182019 [deprecated = true];
    ManagedUserSettingSpecifics managed_user_setting = 186662;
    // TODO(tschumann): Remove once server-side dependencies are resolved.
    ManagedUserSpecifics managed_user = 194582 [deprecated = true];
    // TODO(tschumann): Remove once server-side dependencies are resolved.
    ManagedUserSharedSettingSpecifics managed_user_shared_setting = 202026
        [deprecated = true];
    AppListSpecifics app_list = 229170;
    EmptySpecifics managed_user_allowlist = 306060 [deprecated = true];
    AutofillWalletSpecifics autofill_wallet = 306270;
    WalletMetadataSpecifics wallet_metadata = 330441;
    ArcPackageSpecifics arc_package = 340906;
    PrinterSpecifics printer = 410745;
    ReadingListSpecifics reading_list = 411028;
    UserEventSpecifics user_event = 455206;
    UserConsentSpecifics user_consent = 556014;
    SendTabToSelfSpecifics send_tab_to_self = 601980;
    SecurityEventSpecifics security_event = 600372;
    WebAppSpecifics web_app = 673225;
    WifiConfigurationSpecifics wifi_configuration = 662827;
    OsPreferenceSpecifics os_preference = 702141;
    OsPriorityPreferenceSpecifics os_priority_preference = 703915;
    SharingMessageSpecifics sharing_message = 728866;
    AutofillOfferSpecifics autofill_offer = 774329;
    WorkspaceDeskSpecifics workspace_desk = 874841;
    // This is not included in model_type.h because it's currently only used by
    // the server and by Play Services. (crbug.com/1223853)
    WebauthnCredentialSpecifics webauthn_credential = 895275;
  }
  reserved 218175;
  reserved "wifi_credential";
  reserved 223759;
  reserved "article";
  reserved 545005;
  reserved "mountain_share";
}

message EmptySpecifics {}

message SyncEntity {
  // This item's identifier.  In a commit of a new item, this will be a
  // client-generated ID.  If the commit succeeds, the server will generate
  // a globally unique ID and return it to the committing client in the
  // CommitResponse.EntryResponse.  In the context of a GetUpdatesResponse,
  // |id_string| is always the server generated ID.  The original
  // client-generated ID is preserved in the |originator_client_id| field.
  // Present in both GetUpdatesResponse and CommitMessage.
  optional string id_string = 1;

  // An id referencing this item's parent in the hierarchy.  In a
  // CommitMessage, it is accepted for this to be a client-generated temporary
  // ID if there was a new created item with that ID appearing earlier
  // in the message.  In all other situations, it is a server ID.
  // Present in both GetUpdatesResponse and CommitMessage.
  optional string parent_id_string = 2;

  reserved 3;
  reserved "old_parent_id";

  // The version of this item -- a monotonically increasing value that is
  // maintained by for each item.  If zero in a CommitMessage, the server
  // will interpret this entity as a newly-created item and generate a
  // new server ID and an initial version number.  If nonzero in a
  // CommitMessage, this item is treated as an update to an existing item, and
  // the server will use |id_string| to locate the item.  Then, if the item's
  // current version on the server does not match |version|, the commit will
  // fail for that item.  The server will not update it, and will return
  // a result code of CONFLICT.  In a GetUpdatesResponse, |version| is
  // always positive and indentifies the revision of the item data being sent
  // to the client.
  // Present in both GetUpdatesResponse and CommitMessage.
  // WARNING: This field used to be required before M60. Any client before this
  // will fail to deserialize if this field is missing.
  optional int64 version = 4;

  // Last modification time, in milliseconds since Unix epoch.
  // Present in both GetUpdatesResponse and CommitMessage.
  optional int64 mtime = 5;

  // Creation time, in milliseconds since Unix epoch.
  // Present in both GetUpdatesResponse and CommitMessage.
  optional int64 ctime = 6;

  // The name of this item.
  // Historical note:
  //   Since November 2010, this value is no different from non_unique_name.
  //   Before then, server implementations would maintain a unique-within-parent
  //   value separate from its base, "non-unique" value.  Clients had not
  //   depended on the uniqueness of the property since November 2009; it was
  //   removed from Chromium by http://codereview.chromium.org/371029 .
  // Present in both GetUpdatesResponse and CommitMessage.
  // WARNING: This field used to be required before M60. Any client before this
  // will fail to deserialize if this field is missing.
  optional string name = 7;

  // The name of this item.  Same as |name|.
  // |non_unique_name| should take precedence over the |name| value if both
  // are supplied.  For efficiency, clients and servers should avoid setting
  // this redundant value.
  // Present in both GetUpdatesResponse and CommitMessage.
  optional string non_unique_name = 8;

  reserved 9;
  reserved "sync_timestamp";

  // If present, this tag identifies this item as being a uniquely
  // instanced item.  The server ensures that there is never more
  // than one entity in a user's store with the same tag value.
  // This value is used to identify and find e.g. the "Google Chrome" settings
  // folder without relying on it existing at a particular path, or having
  // a particular name, in the data store.
  //
  // This variant of the tag is created by the server, so clients can't create
  // an item with a tag using this field.
  //
  // Use client_defined_unique_tag if you want to create one from the client.
  //
  // An item can't have both a client_defined_unique_tag and
  // a server_defined_unique_tag.
  //
  // Present only in GetUpdatesResponse.
  optional string server_defined_unique_tag = 10;

  reserved 11;
  reserved "BookmarkData";
  reserved 12;
  reserved "bookmark_folder";
  reserved 13;
  reserved "bookmark_url";
  reserved 14;
  reserved "bookmark_favicon";

  // Supplies a numeric position for this item, relative to other items with the
  // same parent.  Deprecated in M26, though clients are still required to set
  // it.
  //
  // Present in both GetUpdatesResponse and CommitMessage.
  //
  // At one point this was used as an alternative / supplement to
  // the deprecated |insert_after_item_id|, but now it, too, has been
  // deprecated.
  //
  // In order to maintain compatibility with older clients, newer clients should
  // still set this field.  Its value should be based on the first 8 bytes of
  // this item's |unique_position|.
  //
  // Nerwer clients must also support the receipt of items that contain
  // |position_in_parent| but no |unique_position|.  They should locally convert
  // the given int64 position to a UniquePosition.
  //
  // The conversion from int64 to UniquePosition is as follows:
  // The int64 value will have its sign bit flipped then placed in big endian
  // order as the first 8 bytes of the UniquePosition.  The subsequent bytes of
  // the UniquePosition will consist of the item's unique suffix.
  //
  // Conversion from UniquePosition to int64 reverses this process: the first 8
  // bytes of the position are to be interpreted as a big endian int64 value
  // with its sign bit flipped.
  optional int64 position_in_parent = 15 [deprecated = true];

  // Contains the ID of the element (under the same parent) after which this
  // element resides. An empty string indicates that the element is the first
  // element in the parent.  This value is used during commits to specify
  // a relative position for a position change.  In the context of
  // a GetUpdatesMessage, |position_in_parent| is used instead to
  // communicate position.
  //
  // Present only in CommitMessage.
  //
  // This is deprecated.  Clients are allowed to omit this as long as they
  // include |position_in_parent| instead.
  optional string insert_after_item_id = 16 [deprecated = true];

  reserved 17;
  reserved "extended_attributes";

  // If true, indicates that this item has been (or should be) deleted.
  // Present in both GetUpdatesResponse and CommitMessage.
  optional bool deleted = 18 [default = false];

  // A GUID that identifies the the sync client who initially committed
  // this entity.  This value corresponds to |cache_guid| in CommitMessage.
  // This field, along with |originator_client_item_id|, can be used to
  // reunite the original with its official committed version in the case
  // where a client does not receive or process the commit response for
  // some reason.
  //
  // Present only in GetUpdatesResponse.
  //
  // This field is also used in determining the unique identifier used in
  // bookmarks' unique_position field.
  optional string originator_cache_guid = 19;

  // Item ID as generated by the client that initially created this entity. Used
  // exclusively for bookmarks (other datatypes use client_defined_unique_tag).
  // There are three generation of bookmarks that have populated this field
  // differently, depending on which version of the browser created the
  // bookmark:
  // 1. For bookmarks created before M44 (2015), the field got populated with an
  //    ID that is locally unique, but not globally unique (usually a negative
  //    number).
  // 2. For bookmarks created between M45 and M51, both inclusive, the field got
  //    populated with a globally unique GUID in uppercase form.
  // 3. For bookmarks created with M52 or above, the field gets populated with
  //    a globally unique GUID in lowercase form.
  //
  // Present only in GetUpdatesResponse.
  optional string originator_client_item_id = 20;

  // Extensible container for datatype-specific data.
  // This became available in version 23 of the protocol.
  optional EntitySpecifics specifics = 21;

  // Indicate whether this is a folder or not. Available in version 23+.
  optional bool folder = 22 [default = false];

  // A client defined unique hash for this entity.
  // Similar to server_defined_unique_tag.
  //
  // When initially committing an entity, a client can request that the entity
  // is unique per that account. To do so, the client should specify a
  // client_defined_unique_tag. At most one entity per tag value may exist.
  // per account. The server will enforce uniqueness on this tag
  // and fail attempts to create duplicates of this tag.
  // Will be returned in any updates for this entity.
  //
  // The difference between server_defined_unique_tag and
  // client_defined_unique_tag is the creator of the entity. Server defined
  // tags are entities created by the server at account creation,
  // while client defined tags are entities created by the client at any time.
  //
  // During GetUpdates, a sync entity update will come back with ONE of:
  // a) Originator and cache id - If client committed the item as non "unique"
  // b) Server tag - If server committed the item as unique
  // c) Client tag - If client committed the item as unique
  //
  // May be present in CommitMessages for the initial creation of an entity.
  // If present in Commit updates for the entity, it will be ignored.
  //
  // Available in version 24+.
  //
  // May be returned in GetUpdatesMessage and sent up in CommitMessage.
  //
  optional string client_defined_unique_tag = 23;

  // This positioning system had a relatively short life.  It was made obsolete
  // by |unique_position| before either the client or server made much of an
  // attempt to support it.  In fact, no client ever read or set this field.
  //
  // Deprecated in M26.
  optional bytes ordinal_in_parent = 24 [deprecated = true];

  // This is the fourth attempt at positioning.
  //
  // This field is present in both GetUpdatesResponse and CommitMessage, if the
  // item's type requires it and the client that wrote the item supports it (M26
  // or higher).  Clients must also be prepared to handle updates from clients
  // that do not set this field.
  //
  // This field will not be set for items whose type ignores positioning.
  // Clients should not attempt to read this field on the receipt of an item of
  // a type that ignores positioning.
  //
  // Refer to its definition in unique_position.proto for more information about
  // its internal representation.
  optional UniquePosition unique_position = 25;

  // This used to be a list of sync attachment IDs, but it was never launched
  // and the code has been removed as of M66.
  reserved 26;
  reserved "attachment_id";
}

// This message contains diagnostic information used to correlate
// commit-related traffic with extensions-related mutations to the
// data models in chromium.  It plays no functional role in
// processing this CommitMessage.
message ChromiumExtensionsActivity {
  // The human-readable ID identifying the extension responsible
  // for the traffic reported in this ChromiumExtensionsActivity.
  optional string extension_id = 1;

  // How many times the extension successfully invoked a write
  // operation through the bookmarks API since the last CommitMessage.
  optional uint32 bookmark_writes_since_last_commit = 2;
}

// Client specific configuration information.
message ClientConfigParams {
  // The set of data types this client has enabled. Note that this does not
  // include proxy types, as they do not have protocol field numbers and are
  // placeholder types that implicitly enable protocol types.
  repeated int32 enabled_type_ids = 1;

  // Whether the PROXY_TABS proxy datatype is enabled on this client.
  optional bool tabs_datatype_enabled = 2;

  // Whether the account(s) present in the content area's cookie jar match the
  // chrome account. If multiple accounts are present in the cookie jar, a
  // mismatch implies all of them are different from the chrome account.
  optional bool cookie_jar_mismatch = 3;

  // Indicates that the client is not aware of any other active clients
  // interested in the committed data types. This flag shows that it is not
  // necessary to send invalidations for the committed data. A client is
  // considered active if it's DeviceInfo has updated recent enough.
  optional bool single_client = 4;

  // A list of FCM registration tokens which are obtained from other clients.
  // This list is used by the server to send invalidations to all other clients.
  // If the list is empty, the server should treat this as "there is no
  // information about other clients". In practice, this happens by the next
  // causes:
  // 1. This is the old client which doesn't set this field.
  // 2. There are too many active devices and the list would have too many
  // items.
  // 3. An empty list could also mean that the current client is the only
  // client. This case should be covered by the |single_client| field instead
  // (otherwise it could be mixed up with older clients). The server doesn't
  // have to use this field and can ignore it.
  repeated string devices_fcm_registration_tokens = 5;
}

message CommitMessage {
  repeated SyncEntity entries = 1;

  // A GUID that identifies the committing sync client.  This value will be
  // returned as originator_cache_guid for any new items.
  optional string cache_guid = 2;

  repeated ChromiumExtensionsActivity extensions_activity = 3;

  // The configuration of this client at commit time. Used by the server to
  // make commit-time decisions about how to process datatypes that might
  // involve server-side interaction, and e.g require explicit user intent for
  // syncing a particular data type regardless of whether a commit for that
  // datatype is currently being sent up.
  optional ClientConfigParams config_params = 4;

  // Set of optional per-client datatype contexts.
  repeated DataTypeContext client_contexts = 5;

  // This field need to be 256 bytes if set. This attempts to mitigate CRIME
  // attacks when sync communicate from client to server with compression. So if
  // compression is used, this need to set a 256 random ASCII bytes. If no
  // compression, this field should not be set. The server can ignore the
  // padding.
  optional string padding = 6;
}

message GetUpdatesMessage {
  reserved 1;
  reserved "from_timestamp";

  // Indicates the reason for the GetUpdatesMessage.
  // This was *mostly* deprecated in M29.  GetUpdatesOrigin is the new way to
  // encode the reason for the GetUpdates request, but some parts of the server
  // still rely on this field.  It also still contains the
  // "notifications_enabled" flag which needs to be moved elsewhere before this
  // can be fully removed. See https://crbug.com/510165.
  optional GetUpdatesCallerInfo caller_info = 2;

  // Indicates whether related folders should be fetched.
  optional bool fetch_folders = 3 [default = true];

  // Client-requested limit on the maximum number of updates to return at once.
  // The server may opt to return fewer updates than this amount, but it should
  // not return more.
  optional int32 batch_size = 5;

  // Per-datatype progress marker.
  //
  // With the exception of certain configuration or initial sync requests, the
  // client should include one instance of this field for each enabled data
  // type.
  repeated DataTypeProgressMarker from_progress_marker = 6;

  // Indicates whether the response should be sent in chunks.  This may be
  // needed for devices with limited memory resources.  If true, the response
  // will include one or more ClientToServerResponses, with the first one
  // containing GetUpdatesMetadataResponse, and the remaining ones, if any,
  // containing GetUpdatesStreamingResponse.  These ClientToServerResponses are
  // delimited by a length prefix, which is encoded as a varint.
  optional bool streaming = 7 [default = false];

  // Whether the client needs the server to provide an encryption key for this
  // account.
  // Note: this should typically only be set on the first GetUpdates a client
  // requests. Clients are expected to persist the encryption key from then on.
  // The allowed frequency for requesting encryption keys is much lower than
  // other datatypes, so repeated usage will likely result in throttling.
  optional bool need_encryption_key = 8 [default = false];

  // Whether to create the mobile bookmarks folder if it's not
  // already created.  Set to true by all modern clients.
  optional bool create_mobile_bookmarks_folder = 1000
      [default = false, deprecated = true];

  // This value is an updated version of the GetUpdatesCallerInfo's
  // GetUpdatesSource.  It describes the reason for the GetUpdate request.
  // Introduced in M29.
  optional SyncEnums.GetUpdatesOrigin get_updates_origin = 9;

  // Whether this GU also serves as a retry GU. Any GU that happens after
  // retry timer timeout is a retry GU effectively.
  optional bool is_retry = 10 [default = false];

  // Set of optional per-client datatype contexts.
  repeated DataTypeContext client_contexts = 11;

  reserved 4;
  reserved "requested_types";
}

// Message from a client asking the server to clear its data. This causes the
// server to generate a new store birthday, which allows dealing reliably with
// in-flight requests (in particular commits) from other clients.
message ClearServerDataMessage {
  // No arguments needed as the store birthday and user identifier are part of
  // an enclosing message.
}

// Response to a ClearServerData request.
message ClearServerDataResponse {
  // No result fields necessary. Success/failure is indicated in
  // ClientToServerResponse.
}

// The client must preserve, store, and resend the chip bag with
// every request.  The server depends on the chip bag in order
// to precisely choreograph a client-server state machines.
//
// Because the client stores and sends this data on every request,
// the contents of the chip bag should be kept relatively small.
//
// If the server does not return a chip bag, the client must assume
// that there has been no change to the chip bag.  The client must
// resend the bag of chips it had prior on the next request.
//
// The client must make the chip bag durable if and only if it
// processes the response from the server.
message ChipBag {
  // Server chips are deliberately oqaque, allowing the server
  // to encapsulate its state machine logic.
  optional bytes server_chips = 1;
}

// Information about the syncer's state.
message ClientStatus {
  // Flag to indicate if the client has detected hierarchy conflcits.  The flag
  // is left unset if update application has not been attempted yet.
  //
  // The server should attempt to resolve any hierarchy conflicts when this flag
  // is set.  The client may not assume that any particular action will be
  // taken.  There is no guarantee the problem will be addressed in a reasonable
  // amount of time.
  optional bool hierarchy_conflict_detected = 1;

  // Whether the client has full sync (or, sync the feature) enabled or not.
  optional bool is_sync_feature_enabled = 2;
}

message ClientToServerMessage {
  // |share| field is only used on the server for logging and can sometimes
  // contain empty string. It is still useful for logging username when it can't
  // be derived from access token in case of auth error.
  required string share = 1;

  optional int32 protocol_version = 2 [default = 90];
  enum Contents {
    COMMIT = 1;
    GET_UPDATES = 2;
    DEPRECATED_3 = 3;
    DEPRECATED_4 = 4;
    CLEAR_SERVER_DATA = 5;
  }

  // Each ClientToServerMessage contains one request defined by the
  // message_contents. Each type has a corresponding message field that will be
  // present iff the message is of that type. E.g. a commit message will have a
  // message_contents of COMMIT and its commit field will be present.
  required Contents message_contents = 3;
  optional CommitMessage commit = 4;
  optional GetUpdatesMessage get_updates = 5;
  reserved 6;
  reserved "authenticate";

  reserved 9;

  // Opaque server-provided ID representing an "epoch" of the server-side data.
  // Clients must hand this opaque ID back to the server as part of all requests
  // within the same sync session (i.e. for all requests to the server except
  // the very first GetUpdates request). See analogous field
  // ClientToServerResponse.store_birthday for more details about its lifetime.
  optional string store_birthday = 7;

  // The client sets this if it detects a sync issue. The server will tell it
  // if it should perform a refresh.
  optional bool sync_problem_detected = 8 [default = false];

  // Client side state information for debugging purpose.
  // This is only sent on the first getupdates of every sync cycle,
  // as an optimization to save bandwidth.
  optional DebugInfo debug_info = 10;

  // Per-client state for use by the server. Sent with every message sent to the
  // server.
  optional ChipBag bag_of_chips = 11;

  // Google API key.
  optional string api_key = 12;

  // Client's self-reported state.
  // The client should set this on every message sent to the server, though its
  // member fields may often be unset.
  optional ClientStatus client_status = 13;

  // The ID that our invalidation client used to identify itself to the server.
  // Sending the ID here allows the server to not send notifications of our own
  // changes to our invalidator.
  optional string invalidator_client_id = 14;

  // Identifies this ClientToServerMessage as a clear server data request. This
  // field is present when message_contents is CLEAR_SERVER_DATA.
  optional ClearServerDataMessage clear_server_data = 15;
}

message CommitResponse {
  enum ResponseType {
    SUCCESS = 1;
    CONFLICT = 2;  // You're out of date; update and check your data
    // TODO(ncarter): What's the difference between RETRY and TRANSIENT_ERROR?
    RETRY = 3;            // Someone has a conflicting, non-expired session open
    INVALID_MESSAGE = 4;  // What the client sent was invalid, and trying again
                          // won't help.
    OVER_QUOTA = 5;  // This operation would put you, or you are, over quota
    TRANSIENT_ERROR = 6;  // Something went wrong; try again in a bit
  }
  repeated group EntryResponse = 1 {
    required ResponseType response_type = 2;

    // Sync servers may also return a new ID for an existing item, indicating
    // a new entry's been created to hold the data the client's sending up.
    optional string id_string = 3;

    reserved 4;
    reserved "parent_id_string";

    reserved 5;
    reserved "position_in_parent";

    // The item's current version.
    optional int64 version = 6;

    reserved 7;
    reserved "name";

    reserved 8;
    reserved "non_unique_name";

    optional string error_message = 9;

    // Last modification time (in milliseconds since Unix epoch).  Allows the
    // server to override the client-supplied mtime during a commit operation.
    // TODO(crbug.com/1182252): Delete this field too.
    optional int64 mtime = 10 [deprecated = true];

    message DatatypeSpecificError {
      oneof datatype_error {
        SharingMessageCommitError sharing_message_error = 1;
      }
    }
    // Datatype specific error (if any).
    optional DatatypeSpecificError datatype_specific_error = 11;
  }
}

message GetUpdatesResponse {
  // New sync entries that the client should apply.
  repeated SyncEntity entries = 1;

  reserved 2;
  reserved "new_timestamp";

  reserved 3;
  reserved "newest_timestamp";

  // Approximate count of changes remaining - use this for UI feedback.
  // If present and zero, this estimate is firm: the server has no changes
  // after the current batch.
  optional int64 changes_remaining = 4;

  // Opaque, per-datatype timestamp-like tokens.  Clients should retain and
  // persist the values returned in this field, and present them back to the
  // server to indicate the starting point for future update requests.
  //
  // This will be sent only if the client provided |from_progress_marker|
  // in the update request.
  //
  // The server may provide a new progress marker even if this is the end of
  // the batch, or if there were no new updates on the server; and the client
  // must save these.  If the server does not provide a |new_progress_marker|
  // value for a particular datatype, when the request provided a
  // |from_progress_marker| value for that datatype, the client should
  // interpret this to mean "no change from the previous state" and retain its
  // previous progress-marker value for that datatype.
  //
  // Progress markers in the context of a response will never have the
  // |timestamp_token_for_migration| field set.
  repeated DataTypeProgressMarker new_progress_marker = 5;

  // The current encryption keys associated with this account. Will be set if
  // the GetUpdatesMessage in the request had need_encryption_key == true or
  // the server has updated the set of encryption keys (e.g. due to a key
  // rotation).
  repeated bytes encryption_keys = 6;

  // Set of optional datatype contexts server mutations.
  repeated DataTypeContext context_mutations = 7;
}

message ClientToServerResponse {
  optional CommitResponse commit = 1;
  optional GetUpdatesResponse get_updates = 2;
  reserved 3;
  reserved "authenticate";

  // Up until protocol_version 24, the default was SUCCESS which made it
  // impossible to add new enum values since older clients would parse any
  // out-of-range value as SUCCESS. Starting with 25, unless explicitly set,
  // the error_code will be UNKNOWN so that clients know when they're
  // out-of-date. Note also that when using protocol_version < 25,
  // TRANSIENT_ERROR is not supported. Instead, the server sends back a HTTP
  // 400 error code. This is deprecated now.
  optional SyncEnums.ErrorType error_code = 4 [default = UNKNOWN];
  optional string error_message = 5;

  // Opaque server-provided ID representing an "epoch" of the server-side data,
  // referred to as "birthday" or "store birthday". This ID remains fixed until
  // server-side data gets cleared/reset (e.g. via ClearServerDataMessage),
  // which clients experience as NOT_MY_BIRTHDAY error, and involves clearing
  // all local sync metadata including the cached store birthday.
  //
  // This mechanism allows the server to implement clear-data/reset
  // functionality that reliably identifies and deletes sync entities uploaded
  // before the clear-data/reset event (e.g. via ClearServerDataMessage).
  // Furthermore, it allows the server to deal reliably with in-flight changes
  // from other clients upon clear-data event, because all writes issued with an
  // outdated birthday (which in-flight writes would use) can be detected by the
  // server.
  optional string store_birthday = 6;

  optional ClientCommand client_command = 7;
  optional ProfilingData profiling_data = 8;
  reserved 9;
  reserved 10;
  reserved "stream_metadata";
  reserved 11;
  reserved "stream_data";

  // The data types whose storage has been migrated.  Present when the value of
  // error_code is MIGRATION_DONE.
  repeated int32 migrated_data_type_id = 12;

  message Error {
    optional SyncEnums.ErrorType error_type = 1 [default = UNKNOWN];
    optional string error_description = 2;
    reserved 3;
    reserved "url";
    optional SyncEnums.Action action = 4 [default = UNKNOWN_ACTION];

    // Currently meaningful if |error_type| is throttled or partial_failure.
    // In the throttled case, if this field is absent then the whole client
    // (all datatypes) is throttled.
    // In the partial_failure case, this field denotes partial failures. The
    // client should retry those datatypes with exponential backoff.
    repeated int32 error_data_type_ids = 5;
  }
  optional Error error = 13;

  // The new per-client state for this client. If set, should be persisted and
  // sent with any subsequent ClientToServerMessages.
  optional ChipBag new_bag_of_chips = 14;

  // Present if this ClientToServerResponse is in response to a ClearServerData
  // request.
  optional ClearServerDataResponse clear_server_data = 15;
}

// A message to notify the server of certain sync events. Idempotent. Send these
// to the /event endpoint.
message EventRequest {
  optional SyncDisabledEvent sync_disabled = 1;
}

message EventResponse {}

// A message indicating that the sync engine has been disabled on a client.
message SyncDisabledEvent {
  // The GUID that identifies the sync client.
  optional string cache_guid = 1;

  // The store birthday that the client was using before disabling sync.
  optional string store_birthday = 2;
}