sync.proto revision 731df977c0511bca2206b5f333555b1205ff1f43
1// Copyright (c) 2009 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 7syntax = "proto2"; 8 9option optimize_for = LITE_RUNTIME; 10option retain_unknown_fields = true; 11 12package sync_pb; 13 14// Used for inspecting how long we spent performing operations in different 15// backends. All times must be in millis. 16message ProfilingData { 17 optional int64 meta_data_write_time = 1; 18 optional int64 file_data_write_time = 2; 19 optional int64 user_lookup_time = 3; 20 optional int64 meta_data_read_time = 4; 21 optional int64 file_data_read_time = 5; 22 optional int64 total_request_time = 6; 23} 24 25message EntitySpecifics { 26 // To add new datatype-specific fields to the protocol, extend 27 // EntitySpecifics. First, pick a non-colliding tag number by 28 // picking a revision number of one of your past commits 29 // to src.chromium.org. Then, in a different protocol buffer 30 // definition that includes this, do the following: 31 // 32 // extend EntitySpecifics { 33 // MyDatatypeSpecifics my_datatype = 32222; 34 // } 35 // 36 // where: 37 // - 32222 is the non-colliding tag number you picked earlier. 38 // - MyDatatypeSpecifics is the type (probably a message type defined 39 // in your new .proto file) that you want to associate with each 40 // object of the new datatype. 41 // - my_datatype is the field identifier you'll use to access the 42 // datatype specifics from the code. 43 // 44 // Server implementations are obligated to preserve the contents of 45 // EntitySpecifics when it contains unrecognized extensions. In this 46 // way, it is possible to add new datatype fields without having 47 // to update the server. 48 extensions 30000 to max; 49} 50 51message SyncEntity { 52 // This item's identifier. In a commit of a new item, this will be a 53 // client-generated ID. If the commit succeeds, the server will generate 54 // a globally unique ID and return it to the committing client in the 55 // CommitResponse.EntryResponse. In the context of a GetUpdatesResponse, 56 // |id_string| is always the server generated ID. The original 57 // client-generated ID is preserved in the |originator_client_id| field. 58 // Present in both GetUpdatesResponse and CommitMessage. 59 optional string id_string = 1; 60 61 // An id referencing this item's parent in the hierarchy. In a 62 // CommitMessage, it is accepted for this to be a client-generated temporary 63 // ID if there was a new created item with that ID appearing earlier 64 // in the message. In all other situations, it is a server ID. 65 // Present in both GetUpdatesResponse and CommitMessage. 66 optional string parent_id_string = 2; 67 68 // old_parent_id is only set in commits and indicates the old server 69 // parent(s) to remove. When omitted, the old parent is the same as 70 // the new. 71 // Present only in CommitMessage. 72 optional string old_parent_id = 3; 73 74 // The version of this item -- a monotonically increasing value that is 75 // maintained by for each item. If zero in a CommitMessage, the server 76 // will interpret this entity as a newly-created item and generate a 77 // new server ID and an initial version number. If nonzero in a 78 // CommitMessage, this item is treated as an update to an existing item, and 79 // the server will use |id_string| to locate the item. Then, if the item's 80 // current version on the server does not match |version|, the commit will 81 // fail for that item. The server will not update it, and will return 82 // a result code of CONFLICT. In a GetUpdatesResponse, |version| is 83 // always positive and indentifies the revision of the item data being sent 84 // to the client. 85 // Present in both GetUpdatesResponse and CommitMessage. 86 required int64 version = 4; 87 88 // Last modification time (in java time milliseconds) 89 // Present in both GetUpdatesResponse and CommitMessage. 90 optional int64 mtime = 5; 91 92 // Creation time. 93 // Present in both GetUpdatesResponse and CommitMessage. 94 optional int64 ctime = 6; 95 96 // A unique-in-the parent name for this item. 97 // Present in both GetUpdatesResponse and CommitMessage. 98 required string name = 7; 99 100 // non_unique_name holds the base name stored serverside, which is different 101 // from |name| when |name| has been suffixed in a way to make it unique 102 // among its siblings. In a GetUpdatesResponse, |non_unique_name| will 103 // be supplied in addition to |name|, and the client may choose which 104 // field to use depending on its needs. In a CommitMessage, 105 // |non_unique_name| takes precedence over the |name| value if both are 106 // supplied. 107 // Present in both GetUpdatesResponse and CommitMessage. 108 optional string non_unique_name = 8; 109 110 // A value from a monotonically increasing sequence that indicates when 111 // this item was last updated on the server. This is now equivalent 112 // to version. This is now deprecated in favor of version. 113 // Present only in GetUpdatesResponse. 114 optional int64 sync_timestamp = 9; 115 116 // If present, this tag identifies this item as being a uniquely 117 // instanced item. The server ensures that there is never more 118 // than one entity in a user's store with the same tag value. 119 // This value is used to identify and find e.g. the "Google Chrome" settings 120 // folder without relying on it existing at a particular path, or having 121 // a particular name, in the data store. 122 // 123 // This variant of the tag is created by the server, so clients can't create 124 // an item with a tag using this field. 125 // 126 // Use client_defined_unique_tag if you want to create one from the client. 127 // 128 // An item can't have both a client_defined_unique_tag and 129 // a server_defined_unique_tag. 130 // 131 // Present only in GetUpdatesResponse. 132 optional string server_defined_unique_tag = 10; 133 134 // If this group is present, it implies that this SyncEntity corresponds to 135 // a bookmark or a bookmark folder. 136 // 137 // This group is deprecated; clients should use the bookmark EntitySpecifics 138 // protocol buffer extension instead. 139 optional group BookmarkData = 11 { 140 // We use a required field to differentiate between a bookmark and a 141 // bookmark folder. 142 // Present in both GetUpdatesMessage and CommitMessage. 143 required bool bookmark_folder = 12; 144 145 // For bookmark objects, contains the bookmark's URL. 146 // Present in both GetUpdatesResponse and CommitMessage. 147 optional string bookmark_url = 13; 148 149 // For bookmark objects, contains the bookmark's favicon. The favicon is 150 // represented as a 16X16 PNG image. 151 // Present in both GetUpdatesResponse and CommitMessage. 152 optional bytes bookmark_favicon = 14; 153 } 154 155 // Supplies a numeric position for this item, relative to other items with 156 // the same parent. This value is only meaningful in server-to-client 157 // contexts; to specify a position in a client-to-server commit context, 158 // use |insert_after_item_id|. 159 // Present only in GetUpdatesResponse. 160 optional int64 position_in_parent = 15; 161 162 // Contains the ID of the element (under the same parent) after which this 163 // element resides. An empty string indicates that the element is the first 164 // element in the parent. This value is used during commits to specify 165 // a relative position for a position change. In the context of 166 // a GetUpdatesMessage, |position_in_parent| is used instead to 167 // communicate position. 168 // Present only in CommitMessage. 169 optional string insert_after_item_id = 16; 170 171 // Arbitrary key/value pairs associated with this item. 172 // Present in both GetUpdatesResponse and CommitMessage. 173 // Deprecated. 174 // optional ExtendedAttributes extended_attributes = 17; 175 176 // If true, indicates that this item has been (or should be) deleted. 177 // Present in both GetUpdatesResponse and CommitMessage. 178 optional bool deleted = 18 [default = false]; 179 180 // A GUID that identifies the the sync client who initially committed 181 // this entity. This value corresponds to |cache_guid| in CommitMessage. 182 // This field, along with |originator_client_item_id|, can be used to 183 // reunite the original with its official committed version in the case 184 // where a client does not receive or process the commit response for 185 // some reason. 186 // Present only in GetUpdatesResponse. 187 optional string originator_cache_guid = 19; 188 189 // The local item id of this entry from the client that initially 190 // committed this entity. Typically a negative integer. 191 // Present only in GetUpdatesResponse. 192 optional string originator_client_item_id = 20; 193 194 // Extensible container for datatype-specific data. 195 // This became available in version 23 of the protocol. 196 optional EntitySpecifics specifics = 21; 197 198 // Indicate whether this is a folder or not. Available in version 23+. 199 optional bool folder = 22 [default = false]; 200 201 // A client defined unique hash for this entity. 202 // Similar to server_defined_unique_tag. 203 // 204 // When initially committing an entity, a client can request that the entity 205 // is unique per that account. To do so, the client should specify a 206 // client_defined_unique_tag. At most one entity per tag value may exist. 207 // per account. The server will enforce uniqueness on this tag 208 // and fail attempts to create duplicates of this tag. 209 // Will be returned in any updates for this entity. 210 // 211 // The difference between server_defined_unique_tag and 212 // client_defined_unique_tag is the creator of the entity. Server defined 213 // tags are entities created by the server at account creation, 214 // while client defined tags are entities created by the client at any time. 215 // 216 // During GetUpdates, a sync entity update will come back with ONE of: 217 // a) Originator and cache id - If client committed the item as non "unique" 218 // b) Server tag - If server committed the item as unique 219 // c) Client tag - If client committed the item as unique 220 // 221 // May be present in CommitMessages for the initial creation of an entity. 222 // If present in Commit updates for the entity, it will be ignored. 223 // 224 // Available in version 24+. 225 // 226 // May be returned in GetUpdatesMessage and sent up in CommitMessage. 227 // 228 optional string client_defined_unique_tag = 23; 229}; 230 231// This message contains diagnostic information used to correlate 232// commit-related traffic with extensions-related mutations to the 233// data models in chromium. It plays no functional role in 234// processing this CommitMessage. 235message ChromiumExtensionsActivity { 236 // The human-readable ID identifying the extension responsible 237 // for the traffic reported in this ChromiumExtensionsActivity. 238 optional string extension_id = 1; 239 240 // How many times the extension successfully invoked a write 241 // operation through the bookmarks API since the last CommitMessage. 242 optional uint32 bookmark_writes_since_last_commit = 2; 243}; 244 245message CommitMessage { 246 repeated SyncEntity entries = 1; 247 248 // A GUID that identifies the committing sync client. This value will be 249 // returned as originator_cache_guid for any new items. 250 optional string cache_guid = 2; 251 252 repeated ChromiumExtensionsActivity extensions_activity = 3; 253}; 254 255message GetUpdatesCallerInfo { 256 enum GetUpdatesSource { 257 UNKNOWN = 0; // The source was not set by the caller. 258 FIRST_UPDATE = 1; // First update from an instance of Chrome. 259 LOCAL = 2; // The source of the update was a local change. 260 NOTIFICATION = 3; // The source of the update was a p2p notification. 261 PERIODIC = 4; // The source of the update was periodic polling. 262 SYNC_CYCLE_CONTINUATION = 5; // The source of the update was a 263 // continuation of a previous update. 264 CLEAR_PRIVATE_DATA = 6; // Source is a call to remove all private data 265 } 266 267 required GetUpdatesSource source = 1; 268 269 // True only if notifications were enabled for this GetUpdateMessage. 270 optional bool notifications_enabled = 2; 271}; 272 273message DataTypeProgressMarker { 274 // An integer identifying the data type whose progress is tracked by this 275 // marker. The legitimate values of this field correspond to the protobuf 276 // field numbers of all EntitySpecifics extensions supported by the server. 277 // These values are externally declared in per-datatype .proto files. 278 optional int32 data_type_id = 1; 279 280 // An opaque-to-the-client sequence of bytes that the server may interpret 281 // as an indicator of the client's knowledge state. If this is empty or 282 // omitted by the client, it indicates that the client is initiating a 283 // a first-time sync of this datatype. Otherwise, clients must supply a 284 // value previously returned by the server in an earlier GetUpdatesResponse. 285 // These values are not comparable or generable on the client. 286 // 287 // The opaque semantics of this field are to afford server implementations 288 // some flexibility in implementing progress tracking. For instance, 289 // a server implementation built on top of a distributed storage service -- 290 // or multiple heterogenous such services -- might need to supply a vector 291 // of totally ordered monotonic update timestamps, rather than a single 292 // monotonically increasing value. Other optimizations may also be 293 // possible if the server is allowed to embed arbitrary information in 294 // the progress token. 295 // 296 // Server implementations should keep the size of these tokens relatively 297 // small, on the order of tens of bytes, and they should remain small 298 // regardless of the number of items synchronized. (A possible bad server 299 // implementation would be for progress_token to contain a list of all the 300 // items ever sent to the client. Servers shouldn't do this.) 301 optional bytes token = 2; 302 303 // Clients that previously downloaded updates synced using the timestamp based 304 // progress tracking mechanism, but which wish to switch over to the opaque 305 // token mechanism can set this field in a GetUpdatesMessage. The server 306 // will perform a get updates operation as normal from the indicated 307 // timestamp, and return only an opaque progress token. 308 optional int64 timestamp_token_for_migration = 3; 309} 310 311message GetUpdatesMessage { 312 // Indicates the client's current progress in downloading updates. A 313 // from_timestamp value of zero means that the client is requesting a first- 314 // time sync. After that point, clients should fill in this value with the 315 // value returned in the last-seen GetUpdatesResponse.new_timestamp. 316 // 317 // from_timestamp has been deprecated; clients should use 318 // |from_progress_marker| instead, which allows more flexibility. 319 optional int64 from_timestamp = 1; 320 321 // Indicates the reason for the GetUpdatesMessage. 322 optional GetUpdatesCallerInfo caller_info = 2; 323 324 // Indicates whether related folders should be fetched. 325 optional bool fetch_folders = 3 [default = true]; 326 327 // The presence of an individual EntitySpecifics extension indicates that the 328 // client requests sync object types associated with that extension. This 329 // determination depends only on the presence of the extension field, not its 330 // contents -- thus clients should send empty extension messages. For 331 // backwards compatibility only bookmark objects will be sent to the client 332 // should requested_types not be present. 333 // 334 // requested_types may contain multiple EntitySpecifics extensions -- in this 335 // event, the server will return items of all the indicated types. 336 // 337 // requested_types has been deprecated; clients should use 338 // |from_progress_marker| instead, which allows more flexibility. 339 optional EntitySpecifics requested_types = 4; 340 341 // Client-requested limit on the maximum number of updates to return at once. 342 // The server may opt to return fewer updates than this amount, but it should 343 // not return more. 344 optional int32 batch_size = 5; 345 346 // Per-datatype progress marker. If present, the server will ignore 347 // the values of requested_types and from_timestamp, using this instead. 348 repeated DataTypeProgressMarker from_progress_marker = 6; 349}; 350 351message AuthenticateMessage { 352 required string auth_token = 1; 353}; 354 355// This message is sent to the server to clear data. An asynchronous 356// response is returned to the client indicating that the server has received 357// the request and has begun to clear data. 358message ClearUserDataMessage { 359} 360 361message ClearUserDataResponse { 362} 363 364message ClientToServerMessage { 365 required string share = 1; 366 optional int32 protocol_version = 2 [default = 24]; 367 enum Contents { 368 COMMIT = 1; 369 GET_UPDATES = 2; 370 AUTHENTICATE = 3; 371 CLEAR_DATA = 4; 372 } 373 374 required Contents message_contents = 3; 375 optional CommitMessage commit = 4; 376 optional GetUpdatesMessage get_updates = 5; 377 optional AuthenticateMessage authenticate = 6; 378 // Request to clear all Chromium data from the server 379 optional ClearUserDataMessage clear_user_data = 9; 380 381 optional string store_birthday = 7; // Opaque store ID; if it changes, duck! 382 // The client sets this if it detects a sync issue. The server will tell it 383 // if it should perform a refresh. 384 optional bool sync_problem_detected = 8 [default = false]; 385}; 386 387message CommitResponse { 388 enum ResponseType { 389 SUCCESS = 1; 390 CONFLICT = 2; // You're out of date; update and check your data 391 // TODO(ncarter): What's the difference between RETRY and TRANSIENT_ERROR? 392 RETRY = 3; // Someone has a conflicting, non-expired session open 393 INVALID_MESSAGE = 4; // What the client sent was invalid, and trying again 394 // won't help. 395 OVER_QUOTA = 5; // This operation would put you, or you are, over quota 396 TRANSIENT_ERROR = 6; // Something went wrong; try again in a bit 397 } 398 repeated group EntryResponse = 1 { 399 required ResponseType response_type = 2; 400 401 // Sync servers may also return a new ID for an existing item, indicating 402 // a new entry's been created to hold the data the client's sending up. 403 optional string id_string = 3; 404 405 // should be filled if our parent was assigned a new ID. 406 optional string parent_id_string = 4; 407 408 // This value is the same as the position_in_parent value returned within 409 // the SyncEntity message in GetUpdatesResponse. 410 optional int64 position_in_parent = 5; 411 412 // The item's current version. 413 optional int64 version = 6; 414 415 // Allows the server to move-aside an entry as it's being committed. 416 // This name is the same as the name field returned within the SyncEntity 417 // message in GetUpdatesResponse. 418 optional string name = 7; 419 420 // This name is the same as the non_unique_name field returned within the 421 // SyncEntity message in GetUpdatesResponse. 422 optional string non_unique_name = 8; 423 424 optional string error_message = 9; 425 426 } 427}; 428 429message GetUpdatesResponse { 430 // New sync entries that the client should apply. 431 repeated SyncEntity entries = 1; 432 433 // If there are more changes on the server that weren't processed during this 434 // GetUpdates request, the client should send another GetUpdates request and 435 // use new_timestamp as the from_timestamp value within GetUpdatesMessage. 436 // 437 // This field has been deprecated and will be returned only to clients 438 // that set the also-deprecated |from_timestamp| field in the update request. 439 // Clients should use |from_progress_marker| and |new_progress_marker| 440 // instead. 441 optional int64 new_timestamp = 2; 442 443 // DEPRECATED FIELD - server does not set this anymore. 444 optional int64 deprecated_newest_timestamp = 3; 445 446 // Approximate count of changes remaining - use this for UI feedback. 447 // If present and zero, this estimate is firm: the server has no changes 448 // after the current batch. 449 optional int64 changes_remaining = 4; 450 451 // Opaque, per-datatype timestamp-like tokens. A client should use this 452 // field in lieu of new_timestamp, which is deprecated in newer versions 453 // of the protocol. Clients should retain and persist the values returned 454 // in this field, and present them back to the server to indicate the 455 // starting point for future update requests. 456 // 457 // This will be sent only if the client provided |from_progress_marker| 458 // in the update request. 459 // 460 // The server may provide a new progress marker even if this is the end of 461 // the batch, or if there were no new updates on the server; and the client 462 // must save these. If the server does not provide a |new_progress_marker| 463 // value for a particular datatype, when the request provided a 464 // |from_progress_marker| value for that datatype, the client should 465 // interpret this to mean "no change from the previous state" and retain its 466 // previous progress-marker value for that datatype. 467 // 468 // Progress markers in the context of a response will never have the 469 // |timestamp_token_for_migration| field set. 470 repeated DataTypeProgressMarker new_progress_marker = 5; 471}; 472 473// A user-identifying struct. For a given Google account the email and display 474// name can change, but obfuscated_id should be constant. 475// The obfuscated id is optional because at least one planned use of the proto 476// (sharing) does not require it. 477message UserIdentification { 478 required string email = 1; // the user's full primary email address. 479 optional string display_name = 2; // the user's display name. 480 optional string obfuscated_id = 3; // an obfuscated, opaque user id. 481}; 482 483message AuthenticateResponse { 484 // Optional only for backward compatibility. 485 optional UserIdentification user = 1; 486}; 487 488message ThrottleParameters { 489 // Deprecated. Remove this from the server side. 490 required int32 min_measure_payload_size = 1; 491 required double target_utilization = 2; 492 required double measure_interval_max = 3; 493 required double measure_interval_min = 4; 494 required double observation_window = 5; 495}; 496 497// A command from the server instructing the client to update settings or 498// perform some operation. 499message ClientCommand { 500 // Time to wait before sending any requests to the server. 501 optional int32 set_sync_poll_interval = 1; // in seconds 502 optional int32 set_sync_long_poll_interval = 2; // in seconds 503 504 optional int32 max_commit_batch_size = 3; 505}; 506 507message ClientToServerResponse { 508 optional CommitResponse commit = 1; 509 optional GetUpdatesResponse get_updates = 2; 510 optional AuthenticateResponse authenticate = 3; 511 optional ClearUserDataResponse clear_user_data = 9; 512 513 enum ErrorType { 514 SUCCESS = 0; 515 ACCESS_DENIED = 1; // Returned when the user doesn't have access to 516 // store (instead of HTTP 401). 517 NOT_MY_BIRTHDAY = 2; // Returned when the server and client disagree on 518 // the store birthday. 519 THROTTLED = 3; // Returned when the store has exceeded the allowed 520 // bandwidth utilization. 521 AUTH_EXPIRED = 4; // Auth token or cookie has expired. 522 USER_NOT_ACTIVATED = 5; // User doesn't have the Chrome bit set on that 523 // Google Account. 524 AUTH_INVALID = 6; // Auth token or cookie is otherwise invalid. 525 CLEAR_PENDING = 7; // A clear of the user data is pending (e.g. 526 // initiated by privacy request). Client should 527 // come back later. 528 } 529 optional ErrorType error_code = 4 [default = SUCCESS]; 530 optional string error_message = 5; 531 532 // Opaque store ID; if it changes, the contents of the client's cache 533 // is meaningless to this server. This happens most typically when 534 // you switch from one storage backend instance (say, a test instance) 535 // to another (say, the official instance). 536 optional string store_birthday = 6; 537 538 optional ClientCommand client_command = 7; 539 optional ProfilingData profiling_data = 8; 540}; 541 542