123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489 |
- // 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/client_commands.proto";
- import "components/sync/protocol/client_debug_info.proto";
- import "components/sync/protocol/data_type_progress_marker.proto";
- import "components/sync/protocol/get_updates_caller_info.proto";
- import "components/sync/protocol/sync_entity.proto";
- import "components/sync/protocol/sync_enums.proto";
- import "components/sync/protocol/sharing_message_specifics.proto";
- // 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. This flag
- // does not take into account whether standalone invalidations are enabled (as
- // opposed to |single_client_with_standalone_invalidations|). However, it's
- // set depending on interested data types of other devices, e.g. if there are
- // other devices but they are not interested in SESSION data type, and current
- // commit request contains only SESSION, it will be set to true.
- 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_with_standalone_invalidations| field instead (otherwise it
- // could be mixed up with older clients). The server doesn't have to use this
- // field and can ignore it. Note that this list does not take into account
- // interested data types from the other clients.
- repeated string devices_fcm_registration_tokens = 5;
- // Similar to |single_client| but takes into account only clients with enabled
- // sync standalone invalidations. When set to true, there are no other clients
- // with sync standalone invalidations interested in the committing types and
- // hence it's not necessary to send out standalone invalidations (it may still
- // be necessary to send out invalidations using the legacy system, see
- // |single_client| instead).
- // Introduced in M105.
- optional bool single_client_with_standalone_invalidations = 6;
- // Similar to |devices_fcm_registration_tokens| but takes into account clients
- // which are subscribed to the data types which are committed in current
- // commit request.
- // 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_with_standalone_invalidations| field instead (otherwise it
- // could be mixed up with older clients). The server doesn't have to use this
- // field and can ignore it.
- // Introduced in M105.
- repeated string fcm_registration_tokens_for_interested_clients = 7;
- }
- 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 {
- // 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];
- // 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 1;
- reserved "from_timestamp";
- reserved 4;
- reserved "requested_types";
- reserved 5;
- reserved "batch_size";
- }
- // 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.
- // TODO(crbug.com/1315573): Deprecated in M103.
- optional bool hierarchy_conflict_detected = 1 [deprecated = true];
- // 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 = 99];
- 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.
- 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;
- reserved 8;
- reserved "profiling_data";
- 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;
- }
|