Home | History | Annotate | Download | only in protocol
      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