components/sync/protocol/sync_entity.proto

// Copyright 2021 The Chromium Authors
// 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/deletion_origin.proto";
import "components/sync/protocol/entity_specifics.proto";
import "components/sync/protocol/unique_position.proto";

// An attachment represents a payload (usually large) that is associated with an
// entity but is not uploaded or downloaded within the Sync HTTP protocol, but
// an external side channel.
message Attachment {
  // Populated by the client only, when a commit is adding a new attachment to
  // an entity (either newly-created entity or a pre-existing one). Note that
  // each entity is associated to at most one attachment, so committing a new
  // blob ID overrides any previous one.
  optional string temporary_blob_id = 1;

  // Set to the timestamp the attachment was last updated.
  optional int64 modification_time_unix_epoch_millis = 2;
}

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.
  // Prior to M123, this field was empty for commit-only types.
  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.
  //
  // Starting with M99, this field is optional and used for legacy bookmarks
  // only:
  // 1. When processing GetUpdatesResponse, it is unused for modern data created
  //    or reuploaded by M94 or above, which populates the parent's GUID in
  //    BookmarkSpecifics (which is sufficient).
  // 2. When issuing CommitMessage, the field is populated for compatibility
  //    with clients before M99.
  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 the server (or more precisely, the storage backend). It is
  // typically a timestamp, in microseconds since the Unix epoch, of the last
  // backend write. Present in both CommitMessage (set by the client) and
  // GetUpdatesResponse (set by the server), and there's also an equivalent
  // field in CommitResponse.
  //
  // In a CommitMessage, `version` is set to zero for newly-created items. For
  // updates to existing items, it is set by the client to the last version the
  // client knew about when sending the commit. If this version does not match
  // the latest version on the server, the commit *may* fail for that item with
  // a result code of CONFLICT. However, this is not guaranteed, and in
  // practice is not implemented for most data types.
  //
  // In a GetUpdatesResponse, `version` is always positive and identifies the
  // revision of the item stored in the server backend. If the returned version
  // is smaller than the version the client already knew, the client will ignore
  // the response.
  //
  // 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 "Bookmark Bar" folder
  // without relying on a particular ID or name.
  //
  // 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_tag_hash if you want to create one from the client.
  //
  // An item can't have both a client_tag_hash 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";

  // Ancient fields, predecessors for `unique_position`, deprecated with M26 and
  // still supported to deal with old incoming data. See field `unique_position`
  // for details as well as the data-upgrading implementation in
  // GetUniquePositionFromSyncEntity().
  optional int64 position_in_parent = 15 [deprecated = true];
  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 unique ID 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_tag_hash).
  // 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.
  // Analogous to server_defined_unique_tag, but allows the client to determine
  // an immutable attribute of the entity in hashed form that makes it unique
  // per user (i.e. at most one entity may exist per client tag hash).
  //
  // This value must be of the form base64(SHA1(client_tag)) where the
  // client_tag is a value derived from the contents of an entity in a
  // type-specific way. Since the hashed contents of the client_tag are exposed
  // to the server via this field, take care when defining it that there is
  // enough entropy to mask any secrets that the server shouldn't learn.
  //
  // The difference between server_defined_unique_tag and
  // client_tag_hash 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 item and cache id - for bookmarks created using old versions
  //    of the browser (latest M93, before https://crrev.com/c/2945119).
  // 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.
  //
  // May be returned in GetUpdatesMessage and sent up in CommitMessage.
  optional string client_tag_hash = 23;

  // Field 23 was previously named client_defined_unique_tag, avoid reuse.
  reserved "client_defined_unique_tag";

  reserved 24;
  reserved "ordinal_in_parent";

  // Introduced in M26, represents ordering among entities, in practice used for
  // bookmarks only. Clients should not assume it is always populated in
  // GetUpdatesMessage due to the following caveats:
  // 1. Tombstones and permanent folders do not populate it (ordering is
  //    irrelevant).
  // 2. It may remain unset by future versions of the client, as long as the
  //    field with the same name is populated inside BookmarkSpecifics. M94 and
  //    above populate both for backward compatibility reasons, but when support
  //    for M93 is retired, modern clients at the time may stop populating this
  //    field.
  // 3. Very old data (last committed by M25 or below, before the field was
  //    introduced) does not include this field, and in that case the legacy
  //    fields `position_in_parent` or `insert_after_item_id` must be honored
  //    instead.
  //
  // May be returned in GetUpdatesMessage and sent up in CommitMessage.
  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";

  // Metadata used for shared data types. Must not be present for regular data
  // types.
  // Introduced in M124.
  message CollaborationMetadata {
    // Attribution metadata for this whole SyncEntity.
    message Attribution {
      // Obfuscated Gaia ID of the user.
      optional string obfuscated_gaia_id = 1;
    }

    // Per field attribution metadata (e.g, tab_group_color, tab_group_name.)
    // Introduced in M141.
    message PerFieldAttribution {
      // Name of the attribution that uniquely identifies the changed field
      // (e.g. tab_group_title). These should have the same values as those
      // provided through the proto FieldOptions. See
      // `SharedTabGroupDataSpecifics` for examples.
      optional string attribution_name = 1;

      // Obfuscated Gaia ID of the user that last modified this.
      optional string last_update_obfuscated_gaia_id = 2;

      // Last modification time of the specific attribution, in milliseconds
      // since Unix epoch.
      optional int64 mtime = 3;
    }

    // Collaboration ID which the current entity belongs to.
    optional string collaboration_id = 1;

    // Information about when the specifics was created.
    optional Attribution creation_attribution = 2;

    // Information about when the specifics was last updated.
    optional Attribution last_update_attribution = 3;

    repeated PerFieldAttribution per_field_attributions = 4;
  }

  optional CollaborationMetadata collaboration = 27;

  // Optionally present in CommitMessage for committed deletions (but may remain
  // unset if the origin is unspecified), it represents which piece of code
  // triggered a deletion. It is a debug-only field with no compatibility
  // guarantees, subject to change over time. The main purpose is to help with
  // investigating and mitigating user reports or incidents that cause data
  // deletion. Introduced in M126.
  optional DeletionOrigin deletion_origin = 28;

  // References an optional attachment (usually large payload) associated with
  // this entity.
  optional Attachment attachment = 29;
}