sync.proto 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489
  1. // Copyright (c) 2012 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. //
  5. // Sync protocol for communication between sync client and server.
  6. // If you change or add any fields in this file, update proto_visitors.h and
  7. // potentially proto_enum_conversions.{h, cc}. If you add new Specifics proto,
  8. // also update proto_value_conversions.{h, cc}.
  9. syntax = "proto2";
  10. option java_multiple_files = true;
  11. option java_package = "org.chromium.components.sync.protocol";
  12. option optimize_for = LITE_RUNTIME;
  13. package sync_pb;
  14. import "components/sync/protocol/client_commands.proto";
  15. import "components/sync/protocol/client_debug_info.proto";
  16. import "components/sync/protocol/data_type_progress_marker.proto";
  17. import "components/sync/protocol/get_updates_caller_info.proto";
  18. import "components/sync/protocol/sync_entity.proto";
  19. import "components/sync/protocol/sync_enums.proto";
  20. import "components/sync/protocol/sharing_message_specifics.proto";
  21. // This message contains diagnostic information used to correlate
  22. // commit-related traffic with extensions-related mutations to the
  23. // data models in chromium. It plays no functional role in
  24. // processing this CommitMessage.
  25. message ChromiumExtensionsActivity {
  26. // The human-readable ID identifying the extension responsible
  27. // for the traffic reported in this ChromiumExtensionsActivity.
  28. optional string extension_id = 1;
  29. // How many times the extension successfully invoked a write
  30. // operation through the bookmarks API since the last CommitMessage.
  31. optional uint32 bookmark_writes_since_last_commit = 2;
  32. }
  33. // Client specific configuration information.
  34. message ClientConfigParams {
  35. // The set of data types this client has enabled. Note that this does not
  36. // include proxy types, as they do not have protocol field numbers and are
  37. // placeholder types that implicitly enable protocol types.
  38. repeated int32 enabled_type_ids = 1;
  39. // Whether the PROXY_TABS proxy datatype is enabled on this client.
  40. optional bool tabs_datatype_enabled = 2;
  41. // Whether the account(s) present in the content area's cookie jar match the
  42. // chrome account. If multiple accounts are present in the cookie jar, a
  43. // mismatch implies all of them are different from the chrome account.
  44. optional bool cookie_jar_mismatch = 3;
  45. // Indicates that the client is not aware of any other active clients
  46. // interested in the committed data types. This flag shows that it is not
  47. // necessary to send invalidations for the committed data. A client is
  48. // considered active if it's DeviceInfo has updated recent enough. This flag
  49. // does not take into account whether standalone invalidations are enabled (as
  50. // opposed to |single_client_with_standalone_invalidations|). However, it's
  51. // set depending on interested data types of other devices, e.g. if there are
  52. // other devices but they are not interested in SESSION data type, and current
  53. // commit request contains only SESSION, it will be set to true.
  54. optional bool single_client = 4;
  55. // A list of FCM registration tokens which are obtained from other clients.
  56. // This list is used by the server to send invalidations to all other clients.
  57. // If the list is empty, the server should treat this as "there is no
  58. // information about other clients". In practice, this happens by the next
  59. // causes:
  60. // 1. This is the old client which doesn't set this field.
  61. // 2. There are too many active devices and the list would have too many
  62. // items.
  63. // 3. An empty list could also mean that the current client is the only
  64. // client. This case should be covered by the
  65. // |single_client_with_standalone_invalidations| field instead (otherwise it
  66. // could be mixed up with older clients). The server doesn't have to use this
  67. // field and can ignore it. Note that this list does not take into account
  68. // interested data types from the other clients.
  69. repeated string devices_fcm_registration_tokens = 5;
  70. // Similar to |single_client| but takes into account only clients with enabled
  71. // sync standalone invalidations. When set to true, there are no other clients
  72. // with sync standalone invalidations interested in the committing types and
  73. // hence it's not necessary to send out standalone invalidations (it may still
  74. // be necessary to send out invalidations using the legacy system, see
  75. // |single_client| instead).
  76. // Introduced in M105.
  77. optional bool single_client_with_standalone_invalidations = 6;
  78. // Similar to |devices_fcm_registration_tokens| but takes into account clients
  79. // which are subscribed to the data types which are committed in current
  80. // commit request.
  81. // A list of FCM registration tokens which are obtained from other clients.
  82. // This list is used by the server to send invalidations to all other clients.
  83. // If the list is empty, the server should treat this as "there is no
  84. // information about other clients". In practice, this happens by the next
  85. // causes:
  86. // 1. This is the old client which doesn't set this field.
  87. // 2. There are too many active devices and the list would have too many
  88. // items.
  89. // 3. An empty list could also mean that the current client is the only
  90. // client. This case should be covered by the
  91. // |single_client_with_standalone_invalidations| field instead (otherwise it
  92. // could be mixed up with older clients). The server doesn't have to use this
  93. // field and can ignore it.
  94. // Introduced in M105.
  95. repeated string fcm_registration_tokens_for_interested_clients = 7;
  96. }
  97. message CommitMessage {
  98. repeated SyncEntity entries = 1;
  99. // A GUID that identifies the committing sync client. This value will be
  100. // returned as originator_cache_guid for any new items.
  101. optional string cache_guid = 2;
  102. repeated ChromiumExtensionsActivity extensions_activity = 3;
  103. // The configuration of this client at commit time. Used by the server to
  104. // make commit-time decisions about how to process datatypes that might
  105. // involve server-side interaction, and e.g require explicit user intent for
  106. // syncing a particular data type regardless of whether a commit for that
  107. // datatype is currently being sent up.
  108. optional ClientConfigParams config_params = 4;
  109. // Set of optional per-client datatype contexts.
  110. repeated DataTypeContext client_contexts = 5;
  111. // This field need to be 256 bytes if set. This attempts to mitigate CRIME
  112. // attacks when sync communicate from client to server with compression. So if
  113. // compression is used, this need to set a 256 random ASCII bytes. If no
  114. // compression, this field should not be set. The server can ignore the
  115. // padding.
  116. optional string padding = 6;
  117. }
  118. message GetUpdatesMessage {
  119. // Indicates the reason for the GetUpdatesMessage.
  120. // This was *mostly* deprecated in M29. GetUpdatesOrigin is the new way to
  121. // encode the reason for the GetUpdates request, but some parts of the server
  122. // still rely on this field. It also still contains the
  123. // "notifications_enabled" flag which needs to be moved elsewhere before this
  124. // can be fully removed. See https://crbug.com/510165.
  125. optional GetUpdatesCallerInfo caller_info = 2;
  126. // Indicates whether related folders should be fetched.
  127. optional bool fetch_folders = 3 [default = true];
  128. // Per-datatype progress marker.
  129. //
  130. // With the exception of certain configuration or initial sync requests, the
  131. // client should include one instance of this field for each enabled data
  132. // type.
  133. repeated DataTypeProgressMarker from_progress_marker = 6;
  134. // Indicates whether the response should be sent in chunks. This may be
  135. // needed for devices with limited memory resources. If true, the response
  136. // will include one or more ClientToServerResponses, with the first one
  137. // containing GetUpdatesMetadataResponse, and the remaining ones, if any,
  138. // containing GetUpdatesStreamingResponse. These ClientToServerResponses are
  139. // delimited by a length prefix, which is encoded as a varint.
  140. optional bool streaming = 7 [default = false];
  141. // Whether the client needs the server to provide an encryption key for this
  142. // account.
  143. // Note: this should typically only be set on the first GetUpdates a client
  144. // requests. Clients are expected to persist the encryption key from then on.
  145. // The allowed frequency for requesting encryption keys is much lower than
  146. // other datatypes, so repeated usage will likely result in throttling.
  147. optional bool need_encryption_key = 8 [default = false];
  148. // Whether to create the mobile bookmarks folder if it's not
  149. // already created. Set to true by all modern clients.
  150. optional bool create_mobile_bookmarks_folder = 1000
  151. [default = false, deprecated = true];
  152. // This value is an updated version of the GetUpdatesCallerInfo's
  153. // GetUpdatesSource. It describes the reason for the GetUpdate request.
  154. // Introduced in M29.
  155. optional SyncEnums.GetUpdatesOrigin get_updates_origin = 9;
  156. // Whether this GU also serves as a retry GU. Any GU that happens after
  157. // retry timer timeout is a retry GU effectively.
  158. optional bool is_retry = 10 [default = false];
  159. // Set of optional per-client datatype contexts.
  160. repeated DataTypeContext client_contexts = 11;
  161. reserved 1;
  162. reserved "from_timestamp";
  163. reserved 4;
  164. reserved "requested_types";
  165. reserved 5;
  166. reserved "batch_size";
  167. }
  168. // Message from a client asking the server to clear its data. This causes the
  169. // server to generate a new store birthday, which allows dealing reliably with
  170. // in-flight requests (in particular commits) from other clients.
  171. message ClearServerDataMessage {
  172. // No arguments needed as the store birthday and user identifier are part of
  173. // an enclosing message.
  174. }
  175. // Response to a ClearServerData request.
  176. message ClearServerDataResponse {
  177. // No result fields necessary. Success/failure is indicated in
  178. // ClientToServerResponse.
  179. }
  180. // The client must preserve, store, and resend the chip bag with
  181. // every request. The server depends on the chip bag in order
  182. // to precisely choreograph a client-server state machines.
  183. //
  184. // Because the client stores and sends this data on every request,
  185. // the contents of the chip bag should be kept relatively small.
  186. //
  187. // If the server does not return a chip bag, the client must assume
  188. // that there has been no change to the chip bag. The client must
  189. // resend the bag of chips it had prior on the next request.
  190. //
  191. // The client must make the chip bag durable if and only if it
  192. // processes the response from the server.
  193. message ChipBag {
  194. // Server chips are deliberately oqaque, allowing the server
  195. // to encapsulate its state machine logic.
  196. optional bytes server_chips = 1;
  197. }
  198. // Information about the syncer's state.
  199. message ClientStatus {
  200. // Flag to indicate if the client has detected hierarchy conflcits. The flag
  201. // is left unset if update application has not been attempted yet.
  202. //
  203. // The server should attempt to resolve any hierarchy conflicts when this flag
  204. // is set. The client may not assume that any particular action will be
  205. // taken. There is no guarantee the problem will be addressed in a reasonable
  206. // amount of time.
  207. // TODO(crbug.com/1315573): Deprecated in M103.
  208. optional bool hierarchy_conflict_detected = 1 [deprecated = true];
  209. // Whether the client has full sync (or, sync the feature) enabled or not.
  210. optional bool is_sync_feature_enabled = 2;
  211. }
  212. message ClientToServerMessage {
  213. // |share| field is only used on the server for logging and can sometimes
  214. // contain empty string. It is still useful for logging username when it can't
  215. // be derived from access token in case of auth error.
  216. required string share = 1;
  217. optional int32 protocol_version = 2 [default = 99];
  218. enum Contents {
  219. COMMIT = 1;
  220. GET_UPDATES = 2;
  221. DEPRECATED_3 = 3;
  222. DEPRECATED_4 = 4;
  223. CLEAR_SERVER_DATA = 5;
  224. }
  225. // Each ClientToServerMessage contains one request defined by the
  226. // message_contents. Each type has a corresponding message field that will be
  227. // present iff the message is of that type. E.g. a commit message will have a
  228. // message_contents of COMMIT and its commit field will be present.
  229. required Contents message_contents = 3;
  230. optional CommitMessage commit = 4;
  231. optional GetUpdatesMessage get_updates = 5;
  232. reserved 6;
  233. reserved "authenticate";
  234. reserved 9;
  235. // Opaque server-provided ID representing an "epoch" of the server-side data.
  236. // Clients must hand this opaque ID back to the server as part of all requests
  237. // within the same sync session (i.e. for all requests to the server except
  238. // the very first GetUpdates request). See analogous field
  239. // ClientToServerResponse.store_birthday for more details about its lifetime.
  240. optional string store_birthday = 7;
  241. // The client sets this if it detects a sync issue. The server will tell it
  242. // if it should perform a refresh.
  243. optional bool sync_problem_detected = 8 [default = false];
  244. // Client side state information for debugging purpose.
  245. // This is only sent on the first getupdates of every sync cycle,
  246. // as an optimization to save bandwidth.
  247. optional DebugInfo debug_info = 10;
  248. // Per-client state for use by the server. Sent with every message sent to the
  249. // server.
  250. optional ChipBag bag_of_chips = 11;
  251. // Google API key.
  252. optional string api_key = 12;
  253. // Client's self-reported state.
  254. // The client should set this on every message sent to the server, though its
  255. // member fields may often be unset.
  256. optional ClientStatus client_status = 13;
  257. // The ID that our invalidation client used to identify itself to the server.
  258. // Sending the ID here allows the server to not send notifications of our own
  259. // changes to our invalidator.
  260. optional string invalidator_client_id = 14;
  261. // Identifies this ClientToServerMessage as a clear server data request. This
  262. // field is present when message_contents is CLEAR_SERVER_DATA.
  263. optional ClearServerDataMessage clear_server_data = 15;
  264. }
  265. message CommitResponse {
  266. enum ResponseType {
  267. SUCCESS = 1;
  268. CONFLICT = 2; // You're out of date; update and check your data
  269. // TODO(ncarter): What's the difference between RETRY and TRANSIENT_ERROR?
  270. RETRY = 3; // Someone has a conflicting, non-expired session open
  271. INVALID_MESSAGE = 4; // What the client sent was invalid, and trying again
  272. // won't help.
  273. OVER_QUOTA = 5; // This operation would put you, or you are, over quota
  274. TRANSIENT_ERROR = 6; // Something went wrong; try again in a bit
  275. }
  276. repeated group EntryResponse = 1 {
  277. required ResponseType response_type = 2;
  278. // Sync servers may also return a new ID for an existing item, indicating
  279. // a new entry's been created to hold the data the client's sending up.
  280. optional string id_string = 3;
  281. reserved 4;
  282. reserved "parent_id_string";
  283. reserved 5;
  284. reserved "position_in_parent";
  285. // The item's current version.
  286. optional int64 version = 6;
  287. reserved 7;
  288. reserved "name";
  289. reserved 8;
  290. reserved "non_unique_name";
  291. optional string error_message = 9;
  292. // Last modification time (in milliseconds since Unix epoch). Allows the
  293. // server to override the client-supplied mtime during a commit operation.
  294. // TODO(crbug.com/1182252): Delete this field too.
  295. optional int64 mtime = 10 [deprecated = true];
  296. message DatatypeSpecificError {
  297. oneof datatype_error {
  298. SharingMessageCommitError sharing_message_error = 1;
  299. }
  300. }
  301. // Datatype specific error (if any).
  302. optional DatatypeSpecificError datatype_specific_error = 11;
  303. }
  304. }
  305. message GetUpdatesResponse {
  306. // New sync entries that the client should apply.
  307. repeated SyncEntity entries = 1;
  308. reserved 2;
  309. reserved "new_timestamp";
  310. reserved 3;
  311. reserved "newest_timestamp";
  312. // Approximate count of changes remaining - use this for UI feedback.
  313. // If present and zero, this estimate is firm: the server has no changes
  314. // after the current batch.
  315. optional int64 changes_remaining = 4;
  316. // Opaque, per-datatype timestamp-like tokens. Clients should retain and
  317. // persist the values returned in this field, and present them back to the
  318. // server to indicate the starting point for future update requests.
  319. //
  320. // This will be sent only if the client provided |from_progress_marker|
  321. // in the update request.
  322. //
  323. // The server may provide a new progress marker even if this is the end of
  324. // the batch, or if there were no new updates on the server; and the client
  325. // must save these. If the server does not provide a |new_progress_marker|
  326. // value for a particular datatype, when the request provided a
  327. // |from_progress_marker| value for that datatype, the client should
  328. // interpret this to mean "no change from the previous state" and retain its
  329. // previous progress-marker value for that datatype.
  330. repeated DataTypeProgressMarker new_progress_marker = 5;
  331. // The current encryption keys associated with this account. Will be set if
  332. // the GetUpdatesMessage in the request had need_encryption_key == true or
  333. // the server has updated the set of encryption keys (e.g. due to a key
  334. // rotation).
  335. repeated bytes encryption_keys = 6;
  336. // Set of optional datatype contexts server mutations.
  337. repeated DataTypeContext context_mutations = 7;
  338. }
  339. message ClientToServerResponse {
  340. optional CommitResponse commit = 1;
  341. optional GetUpdatesResponse get_updates = 2;
  342. reserved 3;
  343. reserved "authenticate";
  344. // Up until protocol_version 24, the default was SUCCESS which made it
  345. // impossible to add new enum values since older clients would parse any
  346. // out-of-range value as SUCCESS. Starting with 25, unless explicitly set,
  347. // the error_code will be UNKNOWN so that clients know when they're
  348. // out-of-date. Note also that when using protocol_version < 25,
  349. // TRANSIENT_ERROR is not supported. Instead, the server sends back a HTTP
  350. // 400 error code. This is deprecated now.
  351. optional SyncEnums.ErrorType error_code = 4 [default = UNKNOWN];
  352. optional string error_message = 5;
  353. // Opaque server-provided ID representing an "epoch" of the server-side data,
  354. // referred to as "birthday" or "store birthday". This ID remains fixed until
  355. // server-side data gets cleared/reset (e.g. via ClearServerDataMessage),
  356. // which clients experience as NOT_MY_BIRTHDAY error, and involves clearing
  357. // all local sync metadata including the cached store birthday.
  358. //
  359. // This mechanism allows the server to implement clear-data/reset
  360. // functionality that reliably identifies and deletes sync entities uploaded
  361. // before the clear-data/reset event (e.g. via ClearServerDataMessage).
  362. // Furthermore, it allows the server to deal reliably with in-flight changes
  363. // from other clients upon clear-data event, because all writes issued with an
  364. // outdated birthday (which in-flight writes would use) can be detected by the
  365. // server.
  366. optional string store_birthday = 6;
  367. optional ClientCommand client_command = 7;
  368. reserved 8;
  369. reserved "profiling_data";
  370. reserved 9;
  371. reserved 10;
  372. reserved "stream_metadata";
  373. reserved 11;
  374. reserved "stream_data";
  375. // The data types whose storage has been migrated. Present when the value of
  376. // error_code is MIGRATION_DONE.
  377. repeated int32 migrated_data_type_id = 12;
  378. message Error {
  379. optional SyncEnums.ErrorType error_type = 1 [default = UNKNOWN];
  380. optional string error_description = 2;
  381. reserved 3;
  382. reserved "url";
  383. optional SyncEnums.Action action = 4 [default = UNKNOWN_ACTION];
  384. // Currently meaningful if |error_type| is throttled or partial_failure.
  385. // In the throttled case, if this field is absent then the whole client
  386. // (all datatypes) is throttled.
  387. // In the partial_failure case, this field denotes partial failures. The
  388. // client should retry those datatypes with exponential backoff.
  389. repeated int32 error_data_type_ids = 5;
  390. }
  391. optional Error error = 13;
  392. // The new per-client state for this client. If set, should be persisted and
  393. // sent with any subsequent ClientToServerMessages.
  394. optional ChipBag new_bag_of_chips = 14;
  395. // Present if this ClientToServerResponse is in response to a ClearServerData
  396. // request.
  397. optional ClearServerDataResponse clear_server_data = 15;
  398. }
  399. // A message to notify the server of certain sync events. Idempotent. Send these
  400. // to the /event endpoint.
  401. message EventRequest {
  402. optional SyncDisabledEvent sync_disabled = 1;
  403. }
  404. message EventResponse {}
  405. // A message indicating that the sync engine has been disabled on a client.
  406. message SyncDisabledEvent {
  407. // The GUID that identifies the sync client.
  408. optional string cache_guid = 1;
  409. // The store birthday that the client was using before disabling sync.
  410. optional string store_birthday = 2;
  411. }