[Sync] Add ordinal_in_parent to SyncEntity/CommitResponse protobuf

chrome/browser/sync/protocol/sync.proto

Index: chrome/browser/sync/protocol/sync.proto
diff --git a/chrome/browser/sync/protocol/sync.proto b/chrome/browser/sync/protocol/sync.proto
index 41ef93302e99faec688e4717b9d228857c8e43f5..a8937e85ce84bb4f3eb153a65bfe47f086d028eb 100644
--- a/chrome/browser/sync/protocol/sync.proto
+++ b/chrome/browser/sync/protocol/sync.proto
@@ -180,6 +180,15 @@ message SyncEntity {
   // |insert_after_item_id|.  Clients should set both values so that they
   // result in a consistent ordering regardless of which choice the server
   // makes.
+  //
+  // This is deprecated: clients should set |ordinal_in_parent|
+  // instead.  In the interim, clients should supply both
+  // |ordinal_in_parent| and |position_in_parent| and continue to honor the
+  // |ordinal_in_parent| value returned in the CommitResponse.
+  //
+  // When both |ordinal_in_parent| and |position_in_parent| are set,
+  // the first 8 bytes of |ordinal_in_parent| should be equal to
+  // the bytes of |position_in_parent| in big-endian order (MSB first).

[ncarter (slow), 2012/02/09 00:54:47]

Since these values are signed, I believe the following is the way we convert
from int64's to byte[]s. Java code from the server:

  private byte[] encodePosition(long position) {
    byte[] result = new byte[8];
    position ^= 0x8000000000000000L;
    for (int i = 7; i >= 0; --i) {
      result[i] = (byte) position;
      position >>= 8;
    }
    return result;
  }

That's a bijection between int64's and byte[8]. The implication being that if
you allow byte[7]'s and shorter to be mapped into byte strings, the result is no
longer bijective.

For this reason we may wish to enforce a minimum byte length of 8. Or not. But
now is the time to make up our mind.

[akalin, 2012/02/09 01:10:23]

You're right.  Clarified comment.
Went with mandating at least 8 bytes.

Also mandated that ordinals cannot be all 0s (so that we can always insert a
position before).

   optional int64 position_in_parent = 15;
 
   // Contains the ID of the element (under the same parent) after which this
@@ -255,6 +264,20 @@ message SyncEntity {
   // May be returned in GetUpdatesMessage and sent up in CommitMessage.
   //
   optional string client_defined_unique_tag = 23;
+
+  // Supplies an ordinal for this item, relative to other items with the
+  // same parent.  Ordinals are ordered lexicographically bytewise.
+  //
+  // Available in version 31+.
+  //
+  // Present in both GetUpdatesResponse and CommitMessage.
+  //
+  // In a CommitMessage context, server implementations may choose whether
+  // to compute a position based on this field, |position_in_parent|, or
+  // |insert_after_item_id|.  Clients should set all values so that they
+  // result in a consistent ordering regardless of which choice the server
+  // makes.
+  optional bytes ordinal_in_parent = 24;
 };
 
 // This message contains diagnostic information used to correlate
@@ -424,7 +447,7 @@ message ClearUserDataResponse {
 
 message ClientToServerMessage {
   required string share = 1;
-  optional int32 protocol_version = 2 [default = 30];
+  optional int32 protocol_version = 2 [default = 31];
   enum Contents {
     COMMIT = 1;
     GET_UPDATES = 2;
@@ -492,6 +515,10 @@ message CommitResponse {
     // Last modification time (in java time milliseconds).  Allows the server
     // to override the client-supplied mtime during a commit operation.
     optional int64 mtime = 10;
+
+    // This value is the same as the ordinal_in_parent value returned within
+    // the SyncEntity message in GetUpdatesResponse.
+    optional bytes ordinal_in_parent = 11;
   }
 };