components/sync/protocol/sync_entity.proto

// Copyright 2021 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.

syntax = "proto2";

option java_multiple_files = true;
option java_package = "org.chromium.components.sync.protocol";

option optimize_for = LITE_RUNTIME;

package sync_pb;

import "components/sync/protocol/entity_specifics.proto";
import "components/sync/protocol/unique_position.proto";

message SyncEntity {
  // This item's identifier.  In a commit of a new item, this will be a
  // client-generated ID.  If the commit succeeds, the server will generate
  // a globally unique ID and return it to the committing client in the
  // CommitResponse.EntryResponse.  In the context of a GetUpdatesResponse,
  // |id_string| is always the server generated ID.  The original
  // client-generated ID is preserved in the |originator_client_id| field.
  // Present in both GetUpdatesResponse and CommitMessage.
  optional string id_string = 1;

  // An id referencing this item's parent in the hierarchy.  In a
  // CommitMessage, it is accepted for this to be a client-generated temporary
  // ID if there was a new created item with that ID appearing earlier
  // in the message.  In all other situations, it is a server ID.
  // Present in both GetUpdatesResponse and CommitMessage.
  optional string parent_id_string = 2;

  reserved 3;
  reserved "old_parent_id";

  // The version of this item -- a monotonically increasing value that is
  // maintained by for each item.  If zero in a CommitMessage, the server
  // will interpret this entity as a newly-created item and generate a
  // new server ID and an initial version number.  If nonzero in a
  // CommitMessage, this item is treated as an update to an existing item, and
  // the server will use |id_string| to locate the item.  Then, if the item's
  // current version on the server does not match |version|, the commit will
  // fail for that item.  The server will not update it, and will return
  // a result code of CONFLICT.  In a GetUpdatesResponse, |version| is
  // always positive and indentifies the revision of the item data being sent
  // to the client.
  // Present in both GetUpdatesResponse and CommitMessage.
  // WARNING: This field used to be required before M60. Any client before this
  // will fail to deserialize if this field is missing.
  optional int64 version = 4;

  // Last modification time, in milliseconds since Unix epoch.
  // Present in both GetUpdatesResponse and CommitMessage.
  optional int64 mtime = 5;

  // Creation time, in milliseconds since Unix epoch.
  // Present in both GetUpdatesResponse and CommitMessage.
  optional int64 ctime = 6;

  // The name of this item.
  // Historical note:
  //   Since November 2010, this value is no different from non_unique_name.
  //   Before then, server implementations would maintain a unique-within-parent
  //   value separate from its base, "non-unique" value.  Clients had not
  //   depended on the uniqueness of the property since November 2009; it was
  //   removed from Chromium by http://codereview.chromium.org/371029 .
  // Present in both GetUpdatesResponse and CommitMessage.
  // WARNING: This field used to be required before M60. Any client before this
  // will fail to deserialize if this field is missing.
  optional string name = 7;

  // The name of this item.  Same as |name|.
  // |non_unique_name| should take precedence over the |name| value if both
  // are supplied.  For efficiency, clients and servers should avoid setting
  // this redundant value.
  // Present in both GetUpdatesResponse and CommitMessage.
  optional string non_unique_name = 8;

  reserved 9;
  reserved "sync_timestamp";

  // If present, this tag identifies this item as being a uniquely
  // instanced item.  The server ensures that there is never more
  // than one entity in a user's store with the same tag value.
  // This value is used to identify and find e.g. the "Google Chrome" settings
  // folder without relying on it existing at a particular path, or having
  // a particular name, in the data store.
  //
  // This variant of the tag is created by the server, so clients can't create
  // an item with a tag using this field.
  //
  // Use client_defined_unique_tag if you want to create one from the client.
  //
  // An item can't have both a client_defined_unique_tag and
  // a server_defined_unique_tag.
  //
  // Present only in GetUpdatesResponse.
  optional string server_defined_unique_tag = 10;

  reserved 11;
  reserved "BookmarkData";
  reserved 12;
  reserved "bookmark_folder";
  reserved 13;
  reserved "bookmark_url";
  reserved 14;
  reserved "bookmark_favicon";

  // Supplies a numeric position for this item, relative to other items with the
  // same parent.  Deprecated in M26, though clients are still required to set
  // it.
  //
  // Present in both GetUpdatesResponse and CommitMessage.
  //
  // At one point this was used as an alternative / supplement to
  // the deprecated |insert_after_item_id|, but now it, too, has been
  // deprecated.
  //
  // In order to maintain compatibility with older clients, newer clients should
  // still set this field.  Its value should be based on the first 8 bytes of
  // this item's |unique_position|.
  //
  // Nerwer clients must also support the receipt of items that contain
  // |position_in_parent| but no |unique_position|.  They should locally convert
  // the given int64 position to a UniquePosition.
  //
  // The conversion from int64 to UniquePosition is as follows:
  // The int64 value will have its sign bit flipped then placed in big endian
  // order as the first 8 bytes of the UniquePosition.  The subsequent bytes of
  // the UniquePosition will consist of the item's unique suffix.
  //
  // Conversion from UniquePosition to int64 reverses this process: the first 8
  // bytes of the position are to be interpreted as a big endian int64 value
  // with its sign bit flipped.
  optional int64 position_in_parent = 15 [deprecated = true];

  // 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.  Clients are allowed to omit this as long as they
  // include |position_in_parent| instead.
  optional string insert_after_item_id = 16 [deprecated = true];

  reserved 17;
  reserved "extended_attributes";

  // 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 determining the unique identifier used in
  // bookmarks' unique_position field.
  optional string originator_cache_guid = 19;

  // Item ID as generated by the client that initially created this entity. Used
  // exclusively for bookmarks (other datatypes use client_defined_unique_tag).
  // There are three generation of bookmarks that have populated this field
  // differently, depending on which version of the browser created the
  // bookmark:
  // 1. For bookmarks created before M44 (2015), the field got populated with an
  //    ID that is locally unique, but not globally unique (usually a negative
  //    number).
  // 2. For bookmarks created between M45 and M51, both inclusive, the field got
  //    populated with a globally unique GUID in uppercase form.
  // 3. For bookmarks created with M52 or above, the field gets populated with
  //    a globally unique GUID in lowercase form.
  //
  // Present only in GetUpdatesResponse.
  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.
  // Similar to server_defined_unique_tag.
  //
  // When initially committing an entity, a client can request that the entity
  // is unique per that account. To do so, the client should specify a
  // client_defined_unique_tag. At most one entity per tag value may exist.
  // per account. The server will enforce uniqueness on this tag
  // and fail attempts to create duplicates of this tag.
  // Will be returned in any updates for this entity.
  //
  // The difference between server_defined_unique_tag and
  // client_defined_unique_tag is the creator of the entity. Server defined
  // tags are entities created by the server at account creation,
  // while client defined tags are entities created by the client at any time.
  //
  // During GetUpdates, a sync entity update will come back with ONE of:
  // a) Originator and cache id - If client committed the item as non "unique"
  // b) Server tag - If server committed the item as unique
  // c) Client tag - If client committed the item as unique
  //
  // 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;

  // 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.  In fact, no client ever read or set this field.
  //
  // Deprecated in M26.
  optional bytes ordinal_in_parent = 24 [deprecated = true];

  // This is the fourth attempt at positioning.
  //
  // This field is present in both GetUpdatesResponse and CommitMessage, if the
  // item's type requires it and the client that wrote the item supports it (M26
  // or higher).  Clients must also be prepared to handle updates from clients
  // that do not set this field.
  //
  // This field will not be set for items whose type ignores positioning.
  // Clients should not attempt to read this field on the receipt of an item of
  // a type that ignores positioning.
  //
  // Refer to its definition in unique_position.proto for more information about
  // its internal representation.
  optional UniquePosition unique_position = 25;

  // This used to be a list of sync attachment IDs, but it was never launched
  // and the code has been removed as of M66.
  reserved 26;
  reserved "attachment_id";
}