components/sync/protocol/entity_metadata.proto

// Copyright 2015 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// If you change or add any fields in this file, update proto_visitors.h and
// potentially proto_enum_conversions.{h, cc}.

syntax = "proto2";

package sync_pb;

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

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

// Sync proto to store entity metadata in data type storage.
message EntityMetadata {
  // A hash based on the client tag and data type.
  // Used for various map lookups. Should always be available.
  // Sent to the server as SyncEntity::client_tag_hash.
  optional string client_tag_hash = 1;

  // The entity's server-assigned ID.
  //
  // Prior to the item's first commit, we leave this value as an empty string.
  // The initial ID for a newly created item has to meet certain uniqueness
  // requirements, and we handle those on the sync thread.
  optional string server_id = 2;

  // Whether or not the entity is deleted.
  optional bool is_deleted = 3;

  // A version number used to track in-progress commits. Each local change
  // increments this number.
  optional int64 sequence_number = 4;

  // The sequence number of the last item known to be successfully committed.
  optional int64 acked_sequence_number = 5;

  // The server version on which this item is based.
  //
  // If there are no local changes, this is the version of the entity as we see
  // it here.
  //
  // If there are local changes, this is the version of the entity on which
  // those changes are based.
  optional int64 server_version = 6 [default = -1];

  // Entity creation and modification timestamps. Assigned by the client and
  // synced by the server, though the server usually doesn't bother to inspect
  // their values. They are encoded as milliseconds since the Unix epoch.
  optional int64 creation_time = 7;
  optional int64 modification_time = 8;

  // A hash of the current entity specifics value. Used to detect whether
  // entity's specifics value has changed without having to keep specifics in
  // memory.
  optional string specifics_hash = 9;

  // A hash of the last specifics known by both the client and server. Used to
  // detect when local commits and remote updates are just for encryption. This
  // value will be the empty string only in the following cases: the entity is
  // in sync with the server, has never been synced, or is deleted.
  optional string base_specifics_hash = 10;

  // Used for positioning entities among their siblings. Relevant only for data
  // types that support positions (e.g bookmarks). Refer to its definition in
  // unique_position.proto for more information about its internal
  // representation.
  optional UniquePosition unique_position = 11;

  // Used only for bookmarks. It's analogous to `specifics_hash` but it
  // exclusively hashes the content of the favicon image, as represented in
  // proto field BookmarkSpecifics.favicon, using base::PersistentHash().
  optional fixed32 bookmark_favicon_hash = 12;

  // Last specifics known by both the client and server. Used during commits to
  // the server in order to prevent data loss caused by older clients dealing
  // with unknown proto fields (fields that were introduced later). Datatypes
  // (DataTypeSyncBridge) may implement logic to trim down (or fully clear)
  // this proto prior to caching, to avoid the memory and I/O overhead of
  // dealing with an extra copy of the data. Introduced in M101.
  optional EntitySpecifics possibly_trimmed_base_specifics = 13;

  // If the entity is deleted, this field will record the chromium version
  // (e.g. 117.0.5875.1) that originated the deletion. Introduced in M117.
  optional string deleted_by_version = 14;

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

    // 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;
  }
  optional CollaborationMetadata collaboration = 15;

  // Optionally present for committed deletions (but may remain unset if the
  // origin is unspecified), it represents which piece of code triggered a
  // deletion. Introduced in M126.
  optional DeletionOrigin deletion_origin = 16;
}