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 7 // Update proto_value_conversions{.h,.cc,_unittest.cc} if you change 8 // any fields in this file. 9 10 syntax = "proto2"; 11 12 option optimize_for = LITE_RUNTIME; 13 option retain_unknown_fields = true; 14 15 package sync_pb; 16 17 import "app_list_specifics.proto"; 18 import "app_notification_specifics.proto"; 19 import "app_setting_specifics.proto"; 20 import "app_specifics.proto"; 21 import "article_specifics.proto"; 22 import "autofill_specifics.proto"; 23 import "bookmark_specifics.proto"; 24 import "client_commands.proto"; 25 import "client_debug_info.proto"; 26 import "device_info_specifics.proto"; 27 import "dictionary_specifics.proto"; 28 import "encryption.proto"; 29 import "experiments_specifics.proto"; 30 import "extension_setting_specifics.proto"; 31 import "extension_specifics.proto"; 32 import "favicon_image_specifics.proto"; 33 import "favicon_tracking_specifics.proto"; 34 import "get_updates_caller_info.proto"; 35 import "history_delete_directive_specifics.proto"; 36 import "nigori_specifics.proto"; 37 import "managed_user_setting_specifics.proto"; 38 import "managed_user_specifics.proto"; 39 import "password_specifics.proto"; 40 import "preference_specifics.proto"; 41 import "priority_preference_specifics.proto"; 42 import "search_engine_specifics.proto"; 43 import "session_specifics.proto"; 44 import "sync_enums.proto"; 45 import "synced_notification_specifics.proto"; 46 import "theme_specifics.proto"; 47 import "typed_url_specifics.proto"; 48 import "unique_position.proto"; 49 50 // Used for inspecting how long we spent performing operations in different 51 // backends. All times must be in millis. 52 message ProfilingData { 53 optional int64 meta_data_write_time = 1; 54 optional int64 file_data_write_time = 2; 55 optional int64 user_lookup_time = 3; 56 optional int64 meta_data_read_time = 4; 57 optional int64 file_data_read_time = 5; 58 optional int64 total_request_time = 6; 59 } 60 61 message EntitySpecifics { 62 // If a datatype is encrypted, this field will contain the encrypted 63 // original EntitySpecifics. The extension for the datatype will continue 64 // to exist, but contain only the default values. 65 // Note that currently passwords employ their own legacy encryption scheme and 66 // do not use this field. 67 optional EncryptedData encrypted = 1; 68 69 // To add new datatype-specific fields to the protocol, extend 70 // EntitySpecifics. First, pick a non-colliding tag number by 71 // picking a revision number of one of your past commits 72 // to src.chromium.org. Then, in a different protocol buffer 73 // definition, define your message type, and add an optional field 74 // to the list below using the unique tag value you selected. 75 // 76 // optional MyDatatypeSpecifics my_datatype = 32222; 77 // 78 // where: 79 // - 32222 is the non-colliding tag number you picked earlier. 80 // - MyDatatypeSpecifics is the type (probably a message type defined 81 // in your new .proto file) that you want to associate with each 82 // object of the new datatype. 83 // - my_datatype is the field identifier you'll use to access the 84 // datatype specifics from the code. 85 // 86 // Server implementations are obligated to preserve the contents of 87 // EntitySpecifics when it contains unrecognized fields. In this 88 // way, it is possible to add new datatype fields without having 89 // to update the server. 90 // 91 // Note: The tag selection process is based on legacy versions of the 92 // protocol which used protobuf extensions. We have kept the process 93 // consistent as the old values cannot change. The 5+ digit nature of the 94 // tags also makes them recognizable (individually and collectively) from 95 // noise in logs and debugging contexts, and creating a divergent subset of 96 // tags would only make things a bit more confusing. 97 98 optional AutofillSpecifics autofill = 31729; 99 optional BookmarkSpecifics bookmark = 32904; 100 optional PreferenceSpecifics preference = 37702; 101 optional TypedUrlSpecifics typed_url = 40781; 102 optional ThemeSpecifics theme = 41210; 103 optional AppNotification app_notification = 45184; 104 optional PasswordSpecifics password = 45873; 105 optional NigoriSpecifics nigori = 47745; 106 optional ExtensionSpecifics extension = 48119; 107 optional AppSpecifics app = 48364; 108 optional SessionSpecifics session = 50119; 109 optional AutofillProfileSpecifics autofill_profile = 63951; 110 optional SearchEngineSpecifics search_engine = 88610; 111 optional ExtensionSettingSpecifics extension_setting = 96159; 112 optional AppSettingSpecifics app_setting = 103656; 113 optional HistoryDeleteDirectiveSpecifics history_delete_directive = 150251; 114 optional SyncedNotificationSpecifics synced_notification = 153108; 115 optional DeviceInfoSpecifics device_info = 154522; 116 optional ExperimentsSpecifics experiments = 161496; 117 optional PriorityPreferenceSpecifics priority_preference = 163425; 118 optional DictionarySpecifics dictionary = 170540; 119 optional FaviconTrackingSpecifics favicon_tracking = 181534; 120 optional FaviconImageSpecifics favicon_image = 182019; 121 optional ManagedUserSettingSpecifics managed_user_setting = 186662; 122 optional ManagedUserSpecifics managed_user = 194582; 123 optional ArticleSpecifics article = 223759; 124 optional AppListSpecifics app_list = 229170; 125 } 126 127 message SyncEntity { 128 // This item's identifier. In a commit of a new item, this will be a 129 // client-generated ID. If the commit succeeds, the server will generate 130 // a globally unique ID and return it to the committing client in the 131 // CommitResponse.EntryResponse. In the context of a GetUpdatesResponse, 132 // |id_string| is always the server generated ID. The original 133 // client-generated ID is preserved in the |originator_client_id| field. 134 // Present in both GetUpdatesResponse and CommitMessage. 135 optional string id_string = 1; 136 137 // An id referencing this item's parent in the hierarchy. In a 138 // CommitMessage, it is accepted for this to be a client-generated temporary 139 // ID if there was a new created item with that ID appearing earlier 140 // in the message. In all other situations, it is a server ID. 141 // Present in both GetUpdatesResponse and CommitMessage. 142 optional string parent_id_string = 2; 143 144 // old_parent_id is only set in commits and indicates the old server 145 // parent(s) to remove. When omitted, the old parent is the same as 146 // the new. 147 // Present only in CommitMessage. 148 optional string old_parent_id = 3; 149 150 // The version of this item -- a monotonically increasing value that is 151 // maintained by for each item. If zero in a CommitMessage, the server 152 // will interpret this entity as a newly-created item and generate a 153 // new server ID and an initial version number. If nonzero in a 154 // CommitMessage, this item is treated as an update to an existing item, and 155 // the server will use |id_string| to locate the item. Then, if the item's 156 // current version on the server does not match |version|, the commit will 157 // fail for that item. The server will not update it, and will return 158 // a result code of CONFLICT. In a GetUpdatesResponse, |version| is 159 // always positive and indentifies the revision of the item data being sent 160 // to the client. 161 // Present in both GetUpdatesResponse and CommitMessage. 162 required int64 version = 4; 163 164 // Last modification time (in java time milliseconds) 165 // Present in both GetUpdatesResponse and CommitMessage. 166 optional int64 mtime = 5; 167 168 // Creation time. 169 // Present in both GetUpdatesResponse and CommitMessage. 170 optional int64 ctime = 6; 171 172 // The name of this item. 173 // Historical note: 174 // Since November 2010, this value is no different from non_unique_name. 175 // Before then, server implementations would maintain a unique-within-parent 176 // value separate from its base, "non-unique" value. Clients had not 177 // depended on the uniqueness of the property since November 2009; it was 178 // removed from Chromium by http://codereview.chromium.org/371029 . 179 // Present in both GetUpdatesResponse and CommitMessage. 180 required string name = 7; 181 182 // The name of this item. Same as |name|. 183 // |non_unique_name| should take precedence over the |name| value if both 184 // are supplied. For efficiency, clients and servers should avoid setting 185 // this redundant value. 186 // Present in both GetUpdatesResponse and CommitMessage. 187 optional string non_unique_name = 8; 188 189 // A value from a monotonically increasing sequence that indicates when 190 // this item was last updated on the server. This is now equivalent 191 // to version. This is now deprecated in favor of version. 192 // Present only in GetUpdatesResponse. 193 optional int64 sync_timestamp = 9; 194 195 // If present, this tag identifies this item as being a uniquely 196 // instanced item. The server ensures that there is never more 197 // than one entity in a user's store with the same tag value. 198 // This value is used to identify and find e.g. the "Google Chrome" settings 199 // folder without relying on it existing at a particular path, or having 200 // a particular name, in the data store. 201 // 202 // This variant of the tag is created by the server, so clients can't create 203 // an item with a tag using this field. 204 // 205 // Use client_defined_unique_tag if you want to create one from the client. 206 // 207 // An item can't have both a client_defined_unique_tag and 208 // a server_defined_unique_tag. 209 // 210 // Present only in GetUpdatesResponse. 211 optional string server_defined_unique_tag = 10; 212 213 // If this group is present, it implies that this SyncEntity corresponds to 214 // a bookmark or a bookmark folder. 215 // 216 // This group is deprecated; clients should use the bookmark EntitySpecifics 217 // protocol buffer extension instead. 218 optional group BookmarkData = 11 { 219 // We use a required field to differentiate between a bookmark and a 220 // bookmark folder. 221 // Present in both GetUpdatesMessage and CommitMessage. 222 required bool bookmark_folder = 12; 223 224 // For bookmark objects, contains the bookmark's URL. 225 // Present in both GetUpdatesResponse and CommitMessage. 226 optional string bookmark_url = 13; 227 228 // For bookmark objects, contains the bookmark's favicon. The favicon is 229 // represented as a 16X16 PNG image. 230 // Present in both GetUpdatesResponse and CommitMessage. 231 optional bytes bookmark_favicon = 14; 232 } 233 234 // Supplies a numeric position for this item, relative to other items with the 235 // same parent. Deprecated in M26, though clients are still required to set 236 // it. 237 // 238 // Present in both GetUpdatesResponse and CommitMessage. 239 // 240 // At one point this was used as an alternative / supplement to 241 // the deprecated |insert_after_item_id|, but now it, too, has been 242 // deprecated. 243 // 244 // In order to maintain compatibility with older clients, newer clients should 245 // still set this field. Its value should be based on the first 8 bytes of 246 // this item's |unique_position|. 247 // 248 // Nerwer clients must also support the receipt of items that contain 249 // |position_in_parent| but no |unique_position|. They should locally convert 250 // the given int64 position to a UniquePosition. 251 // 252 // The conversion from int64 to UniquePosition is as follows: 253 // The int64 value will have its sign bit flipped then placed in big endian 254 // order as the first 8 bytes of the UniquePosition. The subsequent bytes of 255 // the UniquePosition will consist of the item's unique suffix. 256 // 257 // Conversion from UniquePosition to int64 reverses this process: the first 8 258 // bytes of the position are to be interpreted as a big endian int64 value 259 // with its sign bit flipped. 260 optional int64 position_in_parent = 15; 261 262 // Contains the ID of the element (under the same parent) after which this 263 // element resides. An empty string indicates that the element is the first 264 // element in the parent. This value is used during commits to specify 265 // a relative position for a position change. In the context of 266 // a GetUpdatesMessage, |position_in_parent| is used instead to 267 // communicate position. 268 // 269 // Present only in CommitMessage. 270 // 271 // This is deprecated. Clients are allowed to omit this as long as they 272 // include |position_in_parent| instead. 273 optional string insert_after_item_id = 16; 274 275 // Arbitrary key/value pairs associated with this item. 276 // Present in both GetUpdatesResponse and CommitMessage. 277 // Deprecated. 278 // optional ExtendedAttributes extended_attributes = 17; 279 280 // If true, indicates that this item has been (or should be) deleted. 281 // Present in both GetUpdatesResponse and CommitMessage. 282 optional bool deleted = 18 [default = false]; 283 284 // A GUID that identifies the the sync client who initially committed 285 // this entity. This value corresponds to |cache_guid| in CommitMessage. 286 // This field, along with |originator_client_item_id|, can be used to 287 // reunite the original with its official committed version in the case 288 // where a client does not receive or process the commit response for 289 // some reason. 290 // 291 // Present only in GetUpdatesResponse. 292 // 293 // This field is also used in determining the unique identifier used in 294 // bookmarks' unique_position field. 295 optional string originator_cache_guid = 19; 296 297 // The local item id of this entry from the client that initially 298 // committed this entity. Typically a negative integer. 299 // Present only in GetUpdatesResponse. 300 // 301 // This field is also used in determinging the unique identifier used in 302 // bookmarks' unique_position field. 303 optional string originator_client_item_id = 20; 304 305 // Extensible container for datatype-specific data. 306 // This became available in version 23 of the protocol. 307 optional EntitySpecifics specifics = 21; 308 309 // Indicate whether this is a folder or not. Available in version 23+. 310 optional bool folder = 22 [default = false]; 311 312 // A client defined unique hash for this entity. 313 // Similar to server_defined_unique_tag. 314 // 315 // When initially committing an entity, a client can request that the entity 316 // is unique per that account. To do so, the client should specify a 317 // client_defined_unique_tag. At most one entity per tag value may exist. 318 // per account. The server will enforce uniqueness on this tag 319 // and fail attempts to create duplicates of this tag. 320 // Will be returned in any updates for this entity. 321 // 322 // The difference between server_defined_unique_tag and 323 // client_defined_unique_tag is the creator of the entity. Server defined 324 // tags are entities created by the server at account creation, 325 // while client defined tags are entities created by the client at any time. 326 // 327 // During GetUpdates, a sync entity update will come back with ONE of: 328 // a) Originator and cache id - If client committed the item as non "unique" 329 // b) Server tag - If server committed the item as unique 330 // c) Client tag - If client committed the item as unique 331 // 332 // May be present in CommitMessages for the initial creation of an entity. 333 // If present in Commit updates for the entity, it will be ignored. 334 // 335 // Available in version 24+. 336 // 337 // May be returned in GetUpdatesMessage and sent up in CommitMessage. 338 // 339 optional string client_defined_unique_tag = 23; 340 341 // This positioning system had a relatively short life. It was made obsolete 342 // by |unique_position| before either the client or server made much of an 343 // attempt to support it. In fact, no client ever read or set this field. 344 // 345 // Deprecated in M26. 346 optional bytes ordinal_in_parent = 24; 347 348 // This is the fourth attempt at positioning. 349 // 350 // This field is present in both GetUpdatesResponse and CommitMessage, if the 351 // item's type requires it and the client that wrote the item supports it (M26 352 // or higher). Clients must also be prepared to handle updates from clients 353 // that do not set this field. See the comments on 354 // |server_position_in_parent| for more information on how this is handled. 355 // 356 // This field will not be set for items whose type ignores positioning. 357 // Clients should not attempt to read this field on the receipt of an item of 358 // a type that ignores positioning. 359 // 360 // Refer to its definition in unique_position.proto for more information about 361 // its internal representation. 362 optional UniquePosition unique_position = 25; 363 }; 364 365 // This message contains diagnostic information used to correlate 366 // commit-related traffic with extensions-related mutations to the 367 // data models in chromium. It plays no functional role in 368 // processing this CommitMessage. 369 message ChromiumExtensionsActivity { 370 // The human-readable ID identifying the extension responsible 371 // for the traffic reported in this ChromiumExtensionsActivity. 372 optional string extension_id = 1; 373 374 // How many times the extension successfully invoked a write 375 // operation through the bookmarks API since the last CommitMessage. 376 optional uint32 bookmark_writes_since_last_commit = 2; 377 }; 378 379 // Client specific configuration information. 380 message ClientConfigParams { 381 // The set of data types this client has enabled. Note that this does not 382 // include proxy types, as they do not have protocol field numbers and are 383 // placeholder types that implicitly enable protocol types. 384 repeated int32 enabled_type_ids = 1; 385 386 // Whether the PROXY_TABS proxy datatype is enabled on this client. 387 optional bool tabs_datatype_enabled = 2; 388 }; 389 390 message CommitMessage { 391 repeated SyncEntity entries = 1; 392 393 // A GUID that identifies the committing sync client. This value will be 394 // returned as originator_cache_guid for any new items. 395 optional string cache_guid = 2; 396 397 repeated ChromiumExtensionsActivity extensions_activity = 3; 398 399 // The configuration of this client at commit time. Used by the server to 400 // make commit-time decisions about how to process datatypes that might 401 // involve server-side interaction, and e.g require explicit user intent for 402 // syncing a particular data type regardless of whether a commit for that 403 // datatype is currently being sent up. 404 optional ClientConfigParams config_params = 4; 405 }; 406 407 // This message communicates additional per-type information related to 408 // requests with origin GU_TRIGGER. This message is not relevant when any 409 // other origin value is used. 410 // Introduced in M29. 411 message GetUpdateTriggers { 412 // An opaque-to-the-client string of bytes, received through a notification, 413 // that the server may interpret as a hint about the location of the latest 414 // version of the data for this type. 415 // 416 // Note that this will eventually replace the 'optional' field of the same 417 // name defined in the progress marker, but the client and server should 418 // support both until it's safe to deprecate the old one. 419 // 420 // This field was introduced in M29. 421 repeated string notification_hint = 1; 422 423 // This flag is set if the client was forced to drop hints because the number 424 // of queued hints exceeded its limit. The oldest hints will be discarded 425 // first. Introduced in M29. 426 optional bool client_dropped_hints = 2; 427 428 // This flag is set if the invalidation server reports that it may have 429 // dropped some invalidations at some point. The client will also drop any 430 // locally cached hints that are older than the server-did-drop notification. 431 // 432 // TODO(sync): Determine the format for this. 433 // 434 // optional bool server_dropped_hints = 6; 435 436 // This flag is set when the client suspects that its list of invalidation 437 // hints may be incomplete. This may be the case if: 438 // - The client is syncing for the first time. 439 // - The client has just restarted and it was unable to keep track of 440 // invalidations that were received prior to the restart. 441 // - The client's connection to the invalidation server is currently or 442 // was recently broken. 443 // 444 // It's difficult to provide more details here. This is implemented by 445 // setting the flag to false whenever anything that might adversely affect 446 // notifications happens (eg. a crash, restart on a platform that doesn't 447 // support invalidation ack-tracking, transient invalidation error) and is 448 // unset only after we've experienced one successful sync cycle while 449 // notifications were enabled. 450 // 451 // This flag was introduced in M29. 452 optional bool invalidations_out_of_sync = 3; 453 454 // This counts the number of times the syncer has been asked to commit 455 // changes for this type since the last successful sync cycle. The number of 456 // nudges may not be related to the actual number of items modified. It 457 // often correlates with the number of user actions, but that's not always 458 // the case. 459 // Introduced in M29. 460 optional int64 local_modification_nudges = 4; 461 462 // This counts the number of times the syncer has been explicitly asked to 463 // fetch updates for this type since the last successful sync cycle. These 464 // explicit refresh requests should be relatively rare on most platforms, and 465 // associated with user actions. For example, at the time of this writing 466 // the most common (only?) source of refresh requests is when a user opens 467 // the new tab page on a platform that does not support sessions 468 // invalidations. 469 // Introduced in M29. 470 optional int64 datatype_refresh_nudges = 5; 471 } 472 473 message DataTypeProgressMarker { 474 // An integer identifying the data type whose progress is tracked by this 475 // marker. The legitimate values of this field correspond to the protobuf 476 // field numbers of all EntitySpecifics fields supported by the server. 477 // These values are externally declared in per-datatype .proto files. 478 optional int32 data_type_id = 1; 479 480 // An opaque-to-the-client sequence of bytes that the server may interpret 481 // as an indicator of the client's knowledge state. If this is empty or 482 // omitted by the client, it indicates that the client is initiating a 483 // a first-time sync of this datatype. Otherwise, clients must supply a 484 // value previously returned by the server in an earlier GetUpdatesResponse. 485 // These values are not comparable or generable on the client. 486 // 487 // The opaque semantics of this field are to afford server implementations 488 // some flexibility in implementing progress tracking. For instance, 489 // a server implementation built on top of a distributed storage service -- 490 // or multiple heterogenous such services -- might need to supply a vector 491 // of totally ordered monotonic update timestamps, rather than a single 492 // monotonically increasing value. Other optimizations may also be 493 // possible if the server is allowed to embed arbitrary information in 494 // the progress token. 495 // 496 // Server implementations should keep the size of these tokens relatively 497 // small, on the order of tens of bytes, and they should remain small 498 // regardless of the number of items synchronized. (A possible bad server 499 // implementation would be for progress_token to contain a list of all the 500 // items ever sent to the client. Servers shouldn't do this.) 501 optional bytes token = 2; 502 503 // Clients that previously downloaded updates synced using the timestamp based 504 // progress tracking mechanism, but which wish to switch over to the opaque 505 // token mechanism can set this field in a GetUpdatesMessage. The server 506 // will perform a get updates operation as normal from the indicated 507 // timestamp, and return only an opaque progress token. 508 optional int64 timestamp_token_for_migration = 3; 509 510 // An opaque-to-the-client string of bytes, received through a notification, 511 // that the server may interpret as a hint about the location of the latest 512 // version of the data for this type. 513 // 514 // Deprecated in M29. We should use the repeated field version in the 515 // PerClientTypeState instead. 516 optional string notification_hint = 4; 517 518 // This field will be included only in GetUpdates with origin GU_TRIGGER. 519 optional GetUpdateTriggers get_update_triggers = 5; 520 } 521 522 message GetUpdatesMessage { 523 // Indicates the client's current progress in downloading updates. A 524 // from_timestamp value of zero means that the client is requesting a first- 525 // time sync. After that point, clients should fill in this value with the 526 // value returned in the last-seen GetUpdatesResponse.new_timestamp. 527 // 528 // from_timestamp has been deprecated; clients should use 529 // |from_progress_marker| instead, which allows more flexibility. 530 optional int64 from_timestamp = 1; 531 532 // Indicates the reason for the GetUpdatesMessage. 533 // Deprecated in M29. We should eventually rely on GetUpdatesOrigin instead. 534 // Newer clients will support both systems during the transition period. 535 optional GetUpdatesCallerInfo caller_info = 2; 536 537 // Indicates whether related folders should be fetched. 538 optional bool fetch_folders = 3 [default = true]; 539 540 // The presence of an individual EntitySpecifics field indicates that the 541 // client requests sync object types associated with that field. This 542 // determination depends only on the presence of the field, not its 543 // contents -- thus clients should send empty messages as the field value. 544 // For backwards compatibility only bookmark objects will be sent to the 545 // client should requested_types not be present. 546 // 547 // requested_types may contain multiple EntitySpecifics fields -- in this 548 // event, the server will return items of all the indicated types. 549 // 550 // requested_types has been deprecated; clients should use 551 // |from_progress_marker| instead, which allows more flexibility. 552 optional EntitySpecifics requested_types = 4; 553 554 // Client-requested limit on the maximum number of updates to return at once. 555 // The server may opt to return fewer updates than this amount, but it should 556 // not return more. 557 optional int32 batch_size = 5; 558 559 // Per-datatype progress marker. If present, the server will ignore 560 // the values of requested_types and from_timestamp, using this instead. 561 // 562 // With the exception of certain configuration or initial sync requests, the 563 // client should include one instance of this field for each enabled data 564 // type. 565 repeated DataTypeProgressMarker from_progress_marker = 6; 566 567 // Indicates whether the response should be sent in chunks. This may be 568 // needed for devices with limited memory resources. If true, the response 569 // will include one or more ClientToServerResponses, with the frist one 570 // containing GetUpdatesMetadataResponse, and the remaining ones, if any, 571 // containing GetUpdatesStreamingResponse. These ClientToServerResponses are 572 // delimited by a length prefix, which is encoded as a varint. 573 optional bool streaming = 7 [default = false]; 574 575 // Whether the client needs the server to provide an encryption key for this 576 // account. 577 // Note: this should typically only be set on the first GetUpdates a client 578 // requests. Clients are expected to persist the encryption key from then on. 579 // The allowed frequency for requesting encryption keys is much lower than 580 // other datatypes, so repeated usage will likely result in throttling. 581 optional bool need_encryption_key = 8 [default = false]; 582 583 // Whether to create the mobile bookmarks folder if it's not 584 // already created. Should be set to true only by mobile clients. 585 optional bool create_mobile_bookmarks_folder = 1000 [default = false]; 586 587 // This value is an udpated version of the GetUpdatesCallerInfo's 588 // GetUpdatesSource. It describes the reason for the GetUpdate request. 589 // Introduced in M29. 590 optional SyncEnums.GetUpdatesOrigin get_updates_origin = 9; 591 }; 592 593 message AuthenticateMessage { 594 required string auth_token = 1; 595 }; 596 597 message ClearUserDataMessage { 598 }; 599 600 message ClearUserDataResponse { 601 }; 602 603 // The client must preserve, store, and resend the chip bag with 604 // every request. The server depends on the chip bag in order 605 // to precisely choreograph a client-server state machines. 606 // 607 // Because the client stores and sends this data on every request, 608 // the contents of the chip bag should be kept relatively small. 609 // 610 // If the server does not return a chip bag, the client must assume 611 // that there has been no change to the chip bag. The client must 612 // resend the bag of chips it had prior on the next request. 613 // 614 // The client must make the chip bag durable if and only if it 615 // processes the response from the server. 616 message ChipBag { 617 // Server chips are deliberately oqaque, allowing the server 618 // to encapsulate its state machine logic. 619 optional bytes server_chips = 1; 620 } 621 622 // Information about the syncer's state. 623 message ClientStatus { 624 // Flag to indicate if the client has detected hierarchy conflcits. The flag 625 // is left unset if update application has not been attempted yet. 626 // 627 // The server should attempt to resolve any hierarchy conflicts when this flag 628 // is set. The client may not assume that any particular action will be 629 // taken. There is no guarantee the problem will be addressed in a reasonable 630 // amount of time. 631 optional bool hierarchy_conflict_detected = 1; 632 } 633 634 message ClientToServerMessage { 635 required string share = 1; 636 optional int32 protocol_version = 2 [default = 31]; 637 enum Contents { 638 COMMIT = 1; 639 GET_UPDATES = 2; 640 AUTHENTICATE = 3; 641 CLEAR_DATA = 4; 642 } 643 644 required Contents message_contents = 3; 645 optional CommitMessage commit = 4; 646 optional GetUpdatesMessage get_updates = 5; 647 optional AuthenticateMessage authenticate = 6; 648 649 // Request to clear all Chromium data from the server. 650 optional ClearUserDataMessage clear_user_data = 9; 651 652 optional string store_birthday = 7; // Opaque store ID; if it changes, duck! 653 // The client sets this if it detects a sync issue. The server will tell it 654 // if it should perform a refresh. 655 optional bool sync_problem_detected = 8 [default = false]; 656 657 // Client side state information for debugging purpose. 658 // This is only sent on the first getupdates of every sync cycle, 659 // as an optimization to save bandwidth. 660 optional DebugInfo debug_info = 10; 661 662 // Per-client state for use by the server. Sent with every message sent to the 663 // server. 664 optional ChipBag bag_of_chips = 11; 665 666 // Google API key. 667 optional string api_key = 12; 668 669 // Client's self-reported state. 670 // The client should set this on every message sent to the server, though its 671 // member fields may often be unset. 672 optional ClientStatus client_status = 13; 673 674 // The ID that our invalidation client used to identify itself to the server. 675 // Sending the ID here allows the server to not send notifications of our own 676 // changes to our invalidator. 677 optional string invalidator_client_id = 14; 678 }; 679 680 // This request allows the client to convert a specific crash identifier 681 // into more general information (e.g. hash of the crashing call stack) 682 // suitable for upload in an (authenticated) DebugInfo event. 683 message GetCrashInfoRequest { 684 // Id of the uploaded crash. 685 optional string crash_id = 1; 686 687 // Time that the crash occurred. 688 optional int64 crash_time_millis = 2; 689 } 690 691 // Proto to be written in its entirety to the debug info log. 692 message GetCrashInfoResponse { 693 // Hash of the crashing call stack. 694 optional string stack_id = 1; 695 696 // Time of the crash, potentially rounded to remove 697 // significant bits. 698 optional int64 crash_time_millis = 2; 699 } 700 701 message CommitResponse { 702 enum ResponseType { 703 SUCCESS = 1; 704 CONFLICT = 2; // You're out of date; update and check your data 705 // TODO(ncarter): What's the difference between RETRY and TRANSIENT_ERROR? 706 RETRY = 3; // Someone has a conflicting, non-expired session open 707 INVALID_MESSAGE = 4; // What the client sent was invalid, and trying again 708 // won't help. 709 OVER_QUOTA = 5; // This operation would put you, or you are, over quota 710 TRANSIENT_ERROR = 6; // Something went wrong; try again in a bit 711 } 712 repeated group EntryResponse = 1 { 713 required ResponseType response_type = 2; 714 715 // Sync servers may also return a new ID for an existing item, indicating 716 // a new entry's been created to hold the data the client's sending up. 717 optional string id_string = 3; 718 719 // should be filled if our parent was assigned a new ID. 720 optional string parent_id_string = 4; 721 722 // This value is the same as the position_in_parent value returned within 723 // the SyncEntity message in GetUpdatesResponse. There was a time when the 724 // client would attempt to honor this position, but nowadays the server 725 // should ensure it is no different from the position_in_parent sent up in 726 // the commit request and the client should not read it. 727 optional int64 position_in_parent = 5; 728 729 // The item's current version. 730 optional int64 version = 6; 731 732 // Allows the server to move-aside an entry as it's being committed. 733 // This name is the same as the name field returned within the SyncEntity 734 // message in GetUpdatesResponse. 735 optional string name = 7; 736 737 // This name is the same as the non_unique_name field returned within the 738 // SyncEntity message in GetUpdatesResponse. 739 optional string non_unique_name = 8; 740 741 optional string error_message = 9; 742 743 // Last modification time (in java time milliseconds). Allows the server 744 // to override the client-supplied mtime during a commit operation. 745 optional int64 mtime = 10; 746 } 747 }; 748 749 message GetUpdatesResponse { 750 // New sync entries that the client should apply. 751 repeated SyncEntity entries = 1; 752 753 // If there are more changes on the server that weren't processed during this 754 // GetUpdates request, the client should send another GetUpdates request and 755 // use new_timestamp as the from_timestamp value within GetUpdatesMessage. 756 // 757 // This field has been deprecated and will be returned only to clients 758 // that set the also-deprecated |from_timestamp| field in the update request. 759 // Clients should use |from_progress_marker| and |new_progress_marker| 760 // instead. 761 optional int64 new_timestamp = 2; 762 763 // DEPRECATED FIELD - server does not set this anymore. 764 optional int64 deprecated_newest_timestamp = 3; 765 766 // Approximate count of changes remaining - use this for UI feedback. 767 // If present and zero, this estimate is firm: the server has no changes 768 // after the current batch. 769 optional int64 changes_remaining = 4; 770 771 // Opaque, per-datatype timestamp-like tokens. A client should use this 772 // field in lieu of new_timestamp, which is deprecated in newer versions 773 // of the protocol. Clients should retain and persist the values returned 774 // in this field, and present them back to the server to indicate the 775 // starting point for future update requests. 776 // 777 // This will be sent only if the client provided |from_progress_marker| 778 // in the update request. 779 // 780 // The server may provide a new progress marker even if this is the end of 781 // the batch, or if there were no new updates on the server; and the client 782 // must save these. If the server does not provide a |new_progress_marker| 783 // value for a particular datatype, when the request provided a 784 // |from_progress_marker| value for that datatype, the client should 785 // interpret this to mean "no change from the previous state" and retain its 786 // previous progress-marker value for that datatype. 787 // 788 // Progress markers in the context of a response will never have the 789 // |timestamp_token_for_migration| field set. 790 repeated DataTypeProgressMarker new_progress_marker = 5; 791 792 // The current encryption keys associated with this account. Will be set if 793 // the GetUpdatesMessage in the request had need_encryption_key == true or 794 // the server has updated the set of encryption keys (e.g. due to a key 795 // rotation). 796 repeated bytes encryption_keys = 6; 797 }; 798 799 // The metadata response for GetUpdatesMessage. This response is sent when 800 // streaming is set to true in the request. It is prefixed with a length 801 // delimiter, which is encoded in varint. 802 message GetUpdatesMetadataResponse { 803 // Approximate count of changes remaining. Detailed comment is available in 804 // GetUpdatesResponse. 805 optional int64 changes_remaining = 1; 806 807 // Opaque, per-datatype timestamp-like tokens. Detailed comment is available 808 // in GetUpdatesResponse. 809 repeated DataTypeProgressMarker new_progress_marker = 2; 810 }; 811 812 // The streaming response message for GetUpdatesMessage. This message is sent 813 // when streaming is set to true in the request. There may be multiple 814 // GetUpdatesStreamingResponse messages in a response. This type of messages 815 // is preceded by GetUpdatesMetadataResponse. It is prefixed with a length 816 // delimiter, which is encoded in varint. 817 message GetUpdatesStreamingResponse { 818 // New sync entries that the client should apply. 819 repeated SyncEntity entries = 1; 820 }; 821 822 // A user-identifying struct. For a given Google account the email and display 823 // name can change, but obfuscated_id should be constant. 824 // The obfuscated id is optional because at least one planned use of the proto 825 // (sharing) does not require it. 826 message UserIdentification { 827 required string email = 1; // the user's full primary email address. 828 optional string display_name = 2; // the user's display name. 829 optional string obfuscated_id = 3; // an obfuscated, opaque user id. 830 }; 831 832 message AuthenticateResponse { 833 // Optional only for backward compatibility. 834 optional UserIdentification user = 1; 835 }; 836 837 message ThrottleParameters { 838 // Deprecated. Remove this from the server side. 839 required int32 min_measure_payload_size = 1; 840 required double target_utilization = 2; 841 required double measure_interval_max = 3; 842 required double measure_interval_min = 4; 843 required double observation_window = 5; 844 }; 845 846 message ClientToServerResponse { 847 optional CommitResponse commit = 1; 848 optional GetUpdatesResponse get_updates = 2; 849 optional AuthenticateResponse authenticate = 3; 850 851 // Up until protocol_version 24, the default was SUCCESS which made it 852 // impossible to add new enum values since older clients would parse any 853 // out-of-range value as SUCCESS. Starting with 25, unless explicitly set, 854 // the error_code will be UNKNOWN so that clients know when they're 855 // out-of-date. Note also that when using protocol_version < 25, 856 // TRANSIENT_ERROR is not supported. Instead, the server sends back a HTTP 857 // 400 error code. This is deprecated now. 858 optional SyncEnums.ErrorType error_code = 4 [default = UNKNOWN]; 859 optional string error_message = 5; 860 861 // Opaque store ID; if it changes, the contents of the client's cache 862 // is meaningless to this server. This happens most typically when 863 // you switch from one storage backend instance (say, a test instance) 864 // to another (say, the official instance). 865 optional string store_birthday = 6; 866 867 optional ClientCommand client_command = 7; 868 optional ProfilingData profiling_data = 8; 869 optional ClearUserDataResponse clear_user_data = 9; 870 optional GetUpdatesMetadataResponse stream_metadata = 10; 871 // If GetUpdatesStreamingResponse is contained in the ClientToServerResponse, 872 // none of the other fields (error_code and etc) will be set. 873 optional GetUpdatesStreamingResponse stream_data = 11; 874 875 // The data types whose storage has been migrated. Present when the value of 876 // error_code is MIGRATION_DONE. 877 repeated int32 migrated_data_type_id = 12; 878 879 message Error { 880 optional SyncEnums.ErrorType error_type = 1 [default = UNKNOWN]; 881 optional string error_description = 2; 882 optional string url = 3; 883 optional SyncEnums.Action action = 4 [default = UNKNOWN_ACTION]; 884 885 // Currently only meaningful if |error_type| is throttled. If this field 886 // is absent then the whole client (all datatypes) is throttled. 887 repeated int32 error_data_type_ids = 5; 888 } 889 optional Error error = 13; 890 891 // The new per-client state for this client. If set, should be persisted and 892 // sent with any subsequent ClientToServerMessages. 893 optional ChipBag new_bag_of_chips = 14; 894 }; 895 896