Add more information to sync protocol GU messages

This change allows the client to specify a list of 'hints' when sending
a GetUpdate request to the server.  It also adds a set of flags that can
be used to help the server determine whether or not the list of hints is
complete.

This change also adds flags to help the server infer the reason why the
client is requesting updates.  These flags can be set on a per-data type
basis to indicate if there was a local refresh request or a local change
to the type.

BUG=138613,231693

Review URL: https://chromiumcodereview.appspot.com/13831012

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@198250 0039d316-1c4b-4281-b951-d872f2087c98

6 files changed, 149 insertions, 0 deletions

diff --git a/sync/protocol/get_updates_caller_info.proto b/sync/protocol/get_updates_caller_info.proto
index 86fe9c8..a542324 100644
--- a/sync/protocol/get_updates_caller_info.proto
+++ b/sync/protocol/get_updates_caller_info.proto
@@ -10,6 +10,9 @@ option retain_unknown_fields = true;
 package sync_pb;
 
 message GetUpdatesCallerInfo {
+  // This message was deprecated in M28.  The preferred represenation of this
+  // information is now the GetUpdatesOrigin enum, which is defined in
+  // sync_enums.proto.
   enum GetUpdatesSource {
     UNKNOWN = 0;  // The source was not set by the caller.
     FIRST_UPDATE = 1;  // First request after browser restart.  Not to
diff --git a/sync/protocol/proto_enum_conversions.cc b/sync/protocol/proto_enum_conversions.cc
index ef1d812..f0095a7 100644
--- a/sync/protocol/proto_enum_conversions.cc
+++ b/sync/protocol/proto_enum_conversions.cc
@@ -87,6 +87,23 @@ const char* GetUpdatesSourceString(
   return "";
 }
 
+const char* GetUpdatesOriginString(
+    sync_pb::SyncEnums::GetUpdatesOrigin origin) {
+  ASSERT_ENUM_BOUNDS(sync_pb::SyncEnums, GetUpdatesOrigin,
+                     UNKNOWN_ORIGIN, GU_TRIGGER);
+  switch (origin) {
+    ENUM_CASE(sync_pb::SyncEnums, UNKNOWN_ORIGIN);
+    ENUM_CASE(sync_pb::SyncEnums, PERIODIC);
+    ENUM_CASE(sync_pb::SyncEnums, NEWLY_SUPPORTED_DATATYPE);
+    ENUM_CASE(sync_pb::SyncEnums, MIGRATION);
+    ENUM_CASE(sync_pb::SyncEnums, NEW_CLIENT);
+    ENUM_CASE(sync_pb::SyncEnums, RECONFIGURATION);
+    ENUM_CASE(sync_pb::SyncEnums, GU_TRIGGER);
+  }
+  NOTREACHED();
+  return "";
+}
+
 const char* GetResponseTypeString(
     sync_pb::CommitResponse::ResponseType response_type) {
   ASSERT_ENUM_BOUNDS(sync_pb::CommitResponse, ResponseType, SUCCESS,
diff --git a/sync/protocol/proto_enum_conversions.h b/sync/protocol/proto_enum_conversions.h
index a027858..2f29ed5 100644
--- a/sync/protocol/proto_enum_conversions.h
+++ b/sync/protocol/proto_enum_conversions.h
@@ -33,6 +33,9 @@ SYNC_EXPORT_PRIVATE const char* GetPageTransitionRedirectTypeString(
 SYNC_EXPORT const char* GetUpdatesSourceString(
     sync_pb::GetUpdatesCallerInfo::GetUpdatesSource updates_source);
 
+SYNC_EXPORT const char* GetUpdatesOriginString(
+    sync_pb::SyncEnums::GetUpdatesOrigin origin);
+
 SYNC_EXPORT_PRIVATE const char* GetResponseTypeString(
     sync_pb::CommitResponse::ResponseType response_type);
 
diff --git a/sync/protocol/proto_value_conversions.cc b/sync/protocol/proto_value_conversions.cc
index cb48346..6963eaf 100644
--- a/sync/protocol/proto_value_conversions.cc
+++ b/sync/protocol/proto_value_conversions.cc
@@ -630,6 +630,17 @@ base::DictionaryValue* CommitMessageToValue(
   return value;
 }
 
+base::DictionaryValue* GetUpdateTriggersToValue(
+    const sync_pb::GetUpdateTriggers& proto) {
+  base::DictionaryValue* value = new base::DictionaryValue();
+  SET_STR_REP(notification_hint);
+  SET_BOOL(client_dropped_hints);
+  SET_BOOL(invalidations_out_of_sync);
+  SET_INT64(local_modification_nudges);
+  SET_INT64(datatype_refresh_nudges);
+  return value;
+}
+
 base::DictionaryValue* DataTypeProgressMarkerToValue(
     const sync_pb::DataTypeProgressMarker& proto) {
   base::DictionaryValue* value = new base::DictionaryValue();
@@ -637,6 +648,7 @@ base::DictionaryValue* DataTypeProgressMarkerToValue(
   SET_BYTES(token);
   SET_INT64(timestamp_token_for_migration);
   SET_STR(notification_hint);
+  SET(get_update_triggers, GetUpdateTriggersToValue);
   return value;
 }
 
@@ -658,6 +670,7 @@ base::DictionaryValue* GetUpdatesMessageToValue(
   SET_BOOL(streaming);
   SET_BOOL(need_encryption_key);
   SET_BOOL(create_mobile_bookmarks_folder);
+  SET_ENUM(get_updates_origin, GetUpdatesOriginString);
   return value;
 }
 
diff --git a/sync/protocol/sync.proto b/sync/protocol/sync.proto
index 47f2433..b449e52 100644
--- a/sync/protocol/sync.proto
+++ b/sync/protocol/sync.proto
@@ -398,6 +398,72 @@ message CommitMessage {
   optional ClientConfigParams config_params = 4;
 };
 
+// This message communicates additional per-type information related to
+// requests with origin GU_TRIGGER.  This message is not relevant when any
+// other origin value is used.
+// Introduced in M28.
+message GetUpdateTriggers {
+  // An opaque-to-the-client string of bytes, received through a notification,
+  // that the server may interpret as a hint about the location of the latest
+  // version of the data for this type.
+  //
+  // Note that this will eventually replace the 'optional' field of the same
+  // name defined in the progress marker, but the client and server should
+  // support both until it's safe to deprecate the old one.
+  //
+  // This field was introduced in M28.
+  repeated string notification_hint = 1;
+
+  // This flag is set if the client was forced to drop hints because the number
+  // of queued hints exceeded its limit.  The oldest hints will be discarded
+  // first.  Introduced in M28.
+  optional bool client_dropped_hints = 2;
+
+  // This flag is set if the invalidation server reports that it may have
+  // dropped some invalidations at some point.  The client will also drop any
+  // locally cached hints that are older than the server-did-drop notification.
+  //
+  // TODO(sync): Determine the format for this.
+  //
+  // optional bool server_dropped_hints = 6;
+
+  // This flag is set when the client suspects that its list of invalidation
+  // hints may be incomplete.  This may be the case if:
+  // - The client is syncing for the first time.
+  // - The client has just restarted and it was unable to keep track of
+  //   invalidations that were received prior to the restart.
+  // - The client's connection to the invalidation server is currently or
+  //   was recently broken.
+  //
+  // It's difficult to provide more details here.  This is implemented by
+  // setting the flag to false whenever anything that might adversely affect
+  // notifications happens (eg. a crash, restart on a platform that doesn't
+  // support invalidation ack-tracking, transient invalidation error) and is
+  // unset only after we've experienced one successful sync cycle while
+  // notifications were enabled.
+  //
+  // This flag was introduced in M28.
+  optional bool invalidations_out_of_sync = 3;
+
+  // This counts the number of times the syncer has been asked to commit
+  // changes for this type since the last successful sync cycle.  The number of
+  // nudges may not be related to the actual number of items modified.  It
+  // often correlates with the number of user actions, but that's not always
+  // the case.
+  // Introduced in M28.
+  optional int64 local_modification_nudges = 4;
+
+  // This counts the number of times the syncer has been explicitly asked to
+  // fetch updates for this type since the last successful sync cycle.  These
+  // explicit refresh requests should be relatively rare on most platforms, and
+  // associated with user actions.  For example, at the time of this writing
+  // the most common (only?) source of refresh requests is when a user opens
+  // the new tab page on a platform that does not support sessions
+  // invalidations.
+  // Introduced in M28.
+  optional int64 datatype_refresh_nudges = 5;
+}
+
 message DataTypeProgressMarker {
   // An integer identifying the data type whose progress is tracked by this
   // marker.  The legitimate values of this field correspond to the protobuf
@@ -438,7 +504,13 @@ message DataTypeProgressMarker {
   // An opaque-to-the-client string of bytes, received through a notification,
   // that the server may interpret as a hint about the location of the latest
   // version of the data for this type.
+  //
+  // Deprecated in M28.  We should use the repeated field version in the
+  // PerClientTypeState instead.
   optional string notification_hint = 4;
+
+  // This field will be included only in GetUpdates with origin GU_TRIGGER.
+  optional GetUpdateTriggers get_update_triggers = 5;
 }
 
 message GetUpdatesMessage {
@@ -452,6 +524,8 @@ message GetUpdatesMessage {
   optional int64 from_timestamp = 1;
 
   // Indicates the reason for the GetUpdatesMessage.
+  // Deprecated in M28.  We should eventually rely on GetUpdatesOrigin instead.
+  // Newer clients will support both systems during the transition period.
   optional GetUpdatesCallerInfo caller_info = 2;
 
   // Indicates whether related folders should be fetched.
@@ -478,6 +552,10 @@ message GetUpdatesMessage {
 
   // Per-datatype progress marker.  If present, the server will ignore
   // the values of requested_types and from_timestamp, using this instead.
+  //
+  // With the exception of certain configuration or initial sync requests, the
+  // client should include one instance of this field for each enabled data
+  // type.
   repeated DataTypeProgressMarker from_progress_marker = 6;
 
   // Indicates whether the response should be sent in chunks.  This may be
@@ -499,6 +577,11 @@ message GetUpdatesMessage {
   // Whether to create the mobile bookmarks folder if it's not
   // already created.  Should be set to true only by mobile clients.
   optional bool create_mobile_bookmarks_folder = 1000 [default = false];
+
+  // This value is an udpated version of the GetUpdatesCallerInfo's
+  // GetUpdatesSource.  It describes the reason for the GetUpdate request.
+  // Introduced in M28.
+  optional SyncEnums.GetUpdatesOrigin get_updates_origin = 9;
 };
 
 message AuthenticateMessage {
diff --git a/sync/protocol/sync_enums.proto b/sync/protocol/sync_enums.proto
index 30921a5..a928ca2 100644
--- a/sync/protocol/sync_enums.proto
+++ b/sync/protocol/sync_enums.proto
@@ -114,4 +114,34 @@ message SyncEnums {
     TYPE_PHONE = 6;
     TYPE_TABLET = 7;
   }
+
+  // This is the successor to GetUpdatesSource.  It merges the "normal mode"
+  // values (LOCAL, NOTIFICATION and DATATYPE_REFRESH), which were never really
+  // mutually exclusive to being with, into the GU_TRIGGER value.  It also
+  // drops support for some old values that are not supported by newer clients.
+  //
+  // Mind the gaps: Some values are intentionally unused because we want to
+  // keep the values in sync with GetUpdatesSource as much as possible.  Please
+  // don't add any values < 12 unless there's a good reason for it.
+  //
+  // Introduced in M28.
+  enum GetUpdatesOrigin {
+    UNKNOWN_ORIGIN = 0;  // The source was not set by the caller.
+    PERIODIC = 4;  // The source of the update was periodic polling.
+    NEWLY_SUPPORTED_DATATYPE = 7;   // The client is in configuration mode
+                                    // because it's syncing all datatypes, and
+                                    // support for a new datatype was recently
+                                    // released via a software auto-update.
+    MIGRATION = 8;         // The client is in configuration mode because a
+                           // MIGRATION_DONE error previously returned by the
+                           // server necessitated resynchronization.
+    NEW_CLIENT = 9;        // The client is in configuration mode because the
+                           // user enabled sync for the first time.  Not to be
+                           // confused with FIRST_UPDATE.
+    RECONFIGURATION = 10;  // The client is in configuration mode because the
+                           // user opted to sync a different set of datatypes.
+    GU_TRIGGER = 12; // The client is in 'normal' mode.  It may have several
+                     // reasons for requesting an update.  See the per-type
+                     // GetUpdateTriggers message for more details.
+  }
 }