WIP: The Bookmark Position Megapatch

sync/protocol/sync.proto

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 //
 // Sync protocol for communication between sync client and server.
 
 // Update proto_value_conversions{.h,.cc,_unittest.cc} if you change
 // any fields in this file.
 
 syntax = "proto2";
@@ skipping 205 matching lines @@
   // the same parent.
   //
   // Present in both GetUpdatesResponse and CommitMessage.
   //
   // In a CommitMessage context, server implementations may choose whether
   // to compute a position based on this field or based on
   // |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|
+  // This is deprecated: clients should set |unique_position|
   // instead.  But until the production servers fully support
-  // |ordinal_in_parent|, clients should set all three position fields
+  // |unique_position|, clients should set all three position fields
   // (|position_in_parent|, |insert_after_item_id|, and
-  // |ordinal_in_parent| in commits) and continue to respect any
+  // |unique_position| in commits) and continue to respect any
   // |position_in_parent| values returned by CommitResponses.
   //
-  // Similarly, when |ordinal_in_parent| is absent in a GetUpdates and
+  // Similarly, when |unique_position| is absent in a GetUpdates and
   // |position_in_parent| is present, clients should continue to honor
   // the |position_in_parent| value (after transforming it as
   // described below).
   //
-  // When both |ordinal_in_parent| and |position_in_parent| are set,
-  // the first 8 bytes of |ordinal_in_parent| must be equal to the
-  // bytes of flip-sign-bit(|position_in_parent|) in big-endian order
-  // (MSB first), and if those bytes are all zero, a 9th byte equal to
-  // 128 must be added.
+  // When both |unique_position| and |position_in_parent| are set, the first 8
+  // bytes of |unique_position| must be equal to the bytes of
+  // flip-sign-bit(|position_in_parent|) in big-endian order (MSB first).  The
+  // |unique_position| verstion will also include trailing bytes that may
+  // provide more precise position information, a suffix, and a "terminator"
+  // byte (0xFF).
   optional int64 position_in_parent = 15;
 
   // Contains the ID of the element (under the same parent) after which this
   // element resides. An empty string indicates that the element is the first
   // element in the parent.  This value is used during commits to specify
   // a relative position for a position change.  In the context of
   // a GetUpdatesMessage, |position_in_parent| is used instead to
   // communicate position.
   //
   // Present only in CommitMessage.
   // This is deprecated: see comment for |position_in_parent| above.
   optional string insert_after_item_id = 16;
 
   // Arbitrary key/value pairs associated with this item.
   // Present in both GetUpdatesResponse and CommitMessage.
   // Deprecated.
   // optional ExtendedAttributes extended_attributes = 17;
 
   // If true, indicates that this item has been (or should be) deleted.
   // Present in both GetUpdatesResponse and CommitMessage.
   optional bool deleted = 18 [default = false];
 
   // A GUID that identifies the the sync client who initially committed
   // this entity.  This value corresponds to |cache_guid| in CommitMessage.
   // This field, along with |originator_client_item_id|, can be used to
   // reunite the original with its official committed version in the case
   // where a client does not receive or process the commit response for
   // some reason.
+  //
   // Present only in GetUpdatesResponse.
+  //
+  // This field is also used in determinging the unique identifier used in
+  // bookmarks' unique_position field.  It is expected that the string consist
+  // of 16 bytes of data that have been base64 encoded.
   optional string originator_cache_guid = 19;
 
   // The local item id of this entry from the client that initially
   // committed this entity. Typically a negative integer.
   // Present only in GetUpdatesResponse.
+  //
+  // This field is also used in determinging the unique identifier used in
+  // bookmarks' unique_position field.  It is expected that the ID be the string
+  // representation of a negative 64bit integer.
   optional string originator_client_item_id = 20;
 
   // Extensible container for datatype-specific data.
   // This became available in version 23 of the protocol.
   optional EntitySpecifics specifics = 21;
 
   // Indicate whether this is a folder or not. Available in version 23+.
   optional bool folder = 22 [default = false];
 
   // A client defined unique hash for this entity.
@@ skipping 18 matching lines @@
   //
   // May be present in CommitMessages for the initial creation of an entity.
   // If present in Commit updates for the entity, it will be ignored.
   //
   // Available in version 24+.
   //
   // 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.
-  // Ordinals must be at least 8 bytes (for backwards compatibility), and
-  // must not be all zeroes.
+  // This positioning system had a relatively short life.  It was made obsolete
+  // by |unique_position| before either the client or server made much of an
+  // attempt to support it.
+  optional bytes ordinal_in_parent = 24;
+
+  // This is the fourth attempt at positioning.
   //
-  // Clients should not make sure that each item they know of has a
-  // unique ordinal-in-parent.  However, updates from the server might
-  // break this invariant.  In that case, among the items with the
-  // same ordinal-in-parent, a client should randomly pick one, and
-  // then perturb the ordinal-in-parents of all the other ones (within
-  // the bounds of the preceding and succeeding ordinal-in-parent)
-  // until they're unique; a byte of randomness per item should be
-  // more than enough.
+  // Unique positions are unique per-item, since they are guaranteed to
+  // include a fixed-length suffix.  The last byte of a unique position
+  // is always 0xFF, which is appended to the unique suffix.
   //
-  // Available in version 31+.
+  // Prior to both the suffix and terminator is the position information.  This
+  // sequence of bytes with arbitrary length are chosen such that this item
+  // compares to its siblings as desired.
   //
-  // Present in both GetUpdatesResponse and CommitMessage.
+  // Present in both GetUpdatesResponse and CommitMessage, if the client client
+  // that wrote the item supports it.  Older clients will not set this field, so
+  // the receiver will need to convert the |server_position_in_parent| value
+  // which will be present to a unique_position.
   //
-  // 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 field will not be set for items whose type ignores positioning.
+  // Clients will not attempt to read this field on the receipt of an item of a
+  // type that ignores positioning.
+  optional bytes unique_position = 25;
 };
 
 // This message contains diagnostic information used to correlate
 // commit-related traffic with extensions-related mutations to the
 // data models in chromium.  It plays no functional role in
 // processing this CommitMessage.
 message ChromiumExtensionsActivity {
   // The human-readable ID identifying the extension responsible
   // for the traffic reported in this ChromiumExtensionsActivity.
   optional string extension_id = 1;
@@ skipping 377 matching lines @@
     // is absent then the whole client (all datatypes) is throttled.
     repeated int32 error_data_type_ids = 5;
   }
   optional Error error = 13;
 
   // The new per-client state for this client. If set, should be persisted and
   // sent with any subsequent ClientToServerMessages.
   optional ChipBag new_bag_of_chips = 14;
 };