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