blob: c5352c71b61d432f3ca083cc6172c0c7136ada38 [file] [log] [blame]
// 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.
//
// Protobuf representation of the UniquePosition class.
// If you change or add any fields in this file, update proto_visitors.h and
// potentially proto_enum_conversions.{h, cc}.
syntax = "proto2";
option optimize_for = LITE_RUNTIME;
package sync_pb;
// A UniquePosition is a string of bytes.
//
// Unique positions are unique per-item, since they are guaranteed to end with a
// fixed-length suffix that is unique per-item. The position string may not end
// with a '\0' byte.
//
// Prior to the suffix is a series of arbitrary bytes of arbitrary length.
// Items under the same parent are positioned relative to each other by a
// lexicographic comparison of their UniquePosition values.
message UniquePosition {
// History:
//
// Unique positions were first introduced in M28. This change was rolled out
// in such a way that it would try to maintain backwards compatibilty with
// clients that understood only the old int64-based positions.
//
// At first, clients supported only the 'value' field. This version never
// made it to stable. We later added support for the 'compressed_value'
// field, and clients would populate either one or the other.
//
// In M30, we added the custom_compressed_v1 representation. This
// representation was better than the previous implementations in almost every
// way. However, we could not use it right away, since older clients would
// not understand it. We decided to write both the old-style ('value' or
// 'custom_compressed') representation and the 'custom_compressed_v1'
// repersentations to every protobuf during the transition period. Protobufs
// written during this transition period would be readable by clients who
// understand at least one of the two formats.
//
// In M33, we dropped support for writing the backwards-compatibility fields.
// Protobufs written by this version or later are not be intelligible by
// clients with version M29 or older. Those clients will end up making use of
// the old int64 position fallback mechanism.
// The uncompressed string of bytes representing the position.
//
// Deprecated. See history note above.
optional bytes value = 1;
// The client may choose to write a compressed position to this field instead
// of populating the 'value' above. If it chooses to use compression, the
// 'value' field above must be empty. The position value will be compressed
// with gzip and stored in the compressed_value field. The position's
// uncompressed length must be specified and written to the
// uncompressed_length field.
//
// Deprecated. See history note above.
optional bytes compressed_value = 2;
optional uint64 uncompressed_length = 3;
// This encoding uses compression scheme designed especially for unique
// positions. It has the property that X < Y precisely when Compressed(X) <
// Compressed(Y), which is very useful when the most common operation is to
// compare these positions against each other. Their values may remain
// compressed in memory.
//
// The compression scheme is implemented and documented in
// sync/core_impl/base/unique_position.cc.
//
// As of M30, this is the preferred encoding. Newer clients may continue to
// populate the 'value' and 'compressed_value' fields to ensure backwards
// compatibility, but they will always try to read from this field first.
optional bytes custom_compressed_v1 = 4;
}