proto/schema.proto

syntax="proto3";
package snapshotmetadata;

option go_package = "github.com/kubernetes-csi/external-snapshot-metadata/pkg/api";

// The Kubernetes SnapshotMetadata API is very similar to the CSI
// SnapshotMetadata Service API. The only structural differences between the
// two specifications are in some message properties.
// Refs: https://github.com/kubernetes/enhancements/blob/ffb78131af83279b8852ae742ca60ff81498eecd/keps/sig-storage/3314-csi-changed-block-tracking/README.md#the-csi-snapshotmetadata-service-api
// https://github.com/container-storage-interface/spec/pull/551
service SnapshotMetadata {
  rpc GetMetadataAllocated(GetMetadataAllocatedRequest)
    returns (stream GetMetadataAllocatedResponse) {}

  rpc GetMetadataDelta(GetMetadataDeltaRequest)
    returns (stream GetMetadataDeltaResponse) {}
}

enum BlockMetadataType {
  UNKNOWN=0;

  // The FIXED_LENGTH value indicates that data ranges are
  // returned in fixed size blocks.
  FIXED_LENGTH=1;

  // The VARIABLE_LENGTH value indicates that data ranges
  // are returned in potentially variable sized extents.
  VARIABLE_LENGTH=2;
}

// BlockMetadata specifies a data range.
message BlockMetadata {
  // This is the zero based byte position in the volume or snapshot,
  // measured from the start of the object.
  // This field is REQUIRED.
  int64 byte_offset = 1;

  // This is the size of the data range.
  // size_bytes will be greater than zero.
  // This field is REQUIRED.
  int64 size_bytes = 2;
}

// The GetMetadataAllocatedRequest message is used to solicit metadata
// on the allocated blocks of a snapshot: i.e. this identifies the
// data ranges that have valid data as they were the target of some
// previous write operation on the volume.
message GetMetadataAllocatedRequest {
  // This field specifies an audience scoped authentication token presented by client.
  // This token is used to authenticate and authorize the request at server side.
  // This field is REQUIRED.
  string security_token = 1;

  // This field indicates the Namespace where the VolumeSnapshot exists.
  // If not set, the VolumeSnapshot will be looked for in the "default" Namespace.
  // This field is REQUIRED.
  string namespace = 2;

  // This is the VolumeSnapshot object name against which changes
  // are to be computed.
  // This field is REQUIRED.
  string snapshot_name = 3;

  // This indicates the zero based starting byte position in the volume
  // snapshot from which the result should be computed.
  // It is intended to be used to continue a previously interrupted
  // call.
  // The client SHOULD specify this value to be the offset of the byte
  // position immediately after the last byte of the last data range
  // received, if continuing an interrupted operation, or zero if not.
  // The sidecar will ensure that the returned response stream does not
  // contain BlockMetadata tuples that end before the requested
  // starting_offset: i.e. if S is the requested starting_offset, and
  // B0 is block_metadata[0] of the first message in the response
  // stream, then (S < B0.byte_offset + B0.size_bytes) will be true.
  // This field is REQUIRED.
  int64 starting_offset = 4;

  // This is an optional parameter, and if non-zero it specifies the
  // maximum number of tuples to be returned in each
  // GetMetadataAllocatedResponse message returned by the RPC stream.
  // The sidecar will determine an appropriate value if 0, and is
  // always free to send less than the requested value.
  // This field is OPTIONAL.
  int32 max_results = 5;
}

// GetMetadataAllocatedResponse messages are returned in a gRPC stream.
// Cumulatively, they provide information on the allocated data
// ranges in the snapshot.
message GetMetadataAllocatedResponse {
  // This specifies the style used in the BlockMetadata sequence.
  // This value must be the same in all such messages returned by
  // the stream.
  // If block_metadata_type is FIXED_LENGTH, then the size_bytes field
  // of each message in the block_metadata list will be constant.
  // This field is REQUIRED.
  BlockMetadataType block_metadata_type = 1;

  // This returns the capacity of the underlying volume in bytes.
  // This value must be the same in all such messages returned by
  // the stream.
  // This field is REQUIRED.
  int64 volume_capacity_bytes = 2;

  // This is a list of data range tuples.
  // If the value of max_results in the GetMetadataAllocatedRequest
  // message is greater than zero, then the number of entries in this
  // list will be less than or equal to that value.
  // The sidecar will respect the value of starting_offset in the request.
  // The byte_offset fields of adjacent BlockMetadata messages
  // Will be strictly increasing and messages will not overlap:
  // i.e. for any two BlockMetadata messages, A and B, if A is returned
  // before B, then (A.byte_offset + A.size_bytes <= B.byte_offset)
  // will be true.
  // This will also be true if A and B are from block_metadata lists in
  // different GetMetadataAllocatedResponse messages in the gRPC stream.
  // This field is OPTIONAL.
  repeated BlockMetadata block_metadata = 3;
}

// The GetMetadataDeltaRequest message is used to solicit metadata on the data
// ranges that have changed between two snapshots.
message GetMetadataDeltaRequest {
  // This field specifies an audience scoped authentication token presented by client.
  // This token is used to authenticate and authorize the request at server side.
  // This field is REQUIRED.
  string security_token = 1;

  // This field indicates the Namespace where the VolumeSnapshot exists.
  // If not set, the VolumeSnapshot will be looked for in the "default" Namespace.
  // This field is REQUIRED.
  string namespace = 2;

  // This is the VolumeSnapshot object name against which changes
  // are to be computed.
  // This field is REQUIRED.
  string base_snapshot_name = 3;

  // This is the name of a second VolumeSnapshot in the same volume,
  // created after the base snapshot.
  // This field is REQUIRED.
  string target_snapshot_name = 4;

  // This indicates the zero based starting byte position in the volume
  // snapshot from which the result should be computed.
  // It is intended to be used to continue a previously interrupted
  // call.
  // The client SHOULD specify this value to be the offset of the byte
  // position immediately after the last byte of the last data range
  // received, if continuing an interrupted operation, or zero if not.
  // The sidecar will ensure that the returned response stream does not
  // contain BlockMetadata tuples that end before the requested
  // starting_offset: i.e. if S is the requested starting_offset, and
  // B0 is block_metadata[0] of the first message in the response
  // stream, then (S < B0.byte_offset + B0.size_bytes) will be true.
  // This field is REQUIRED.
  int64 starting_offset = 5;

  // This is an optional parameter, and if non-zero it specifies the
  // maximum number of tuples to be returned in each
  // GetMetadataDeltaResponse message returned by the RPC stream.
  // The sidecar will determine an appropriate value if 0, and is
  // always free to send less than the requested value.
  // This field is OPTIONAL.
  int32 max_results = 6;
}

// GetMetadataDeltaResponse messages are returned in a gRPC stream.
// Cumulatively, they provide information on the data ranges that
// have changed between the base and target snapshots specified
// in the GetMetadataDeltaRequest message.
message GetMetadataDeltaResponse {
  // This specifies the style used in the BlockMetadata sequence.
  // This value must be the same in all such messages returned by
  // the stream.
  // If block_metadata_type is FIXED_LENGTH, then the size_bytes field
  // of each message in the block_metadata list will be constant.
  // This field is REQUIRED.
  BlockMetadataType block_metadata_type = 1;

  // This returns the capacity of the underlying volume in bytes.
  // This value must be the same in all such messages returned by
  // the stream.
  // This field is REQUIRED.
  int64 volume_capacity_bytes = 2;

  // This is a list of data range tuples.
  // If the value of max_results in the GetMetadataDeltaRequest message
  // is greater than zero, then the number of entries in this list will
  // be less than or equal to that value.
  // The sidecar will respect the value of starting_offset in the request.
  // The byte_offset fields of adjacent BlockMetadata messages
  // Will be strictly increasing and messages will not overlap:
  // i.e. for any two BlockMetadata messages, A and B, if A is returned
  // before B, then (A.byte_offset + A.size_bytes <= B.byte_offset)
  // will be true.
  // This will also be true if A and B are from block_metadata lists in
  // different GetMetadataDeltaResponse messages in the gRPC stream.
  // This field is OPTIONAL.
  repeated BlockMetadata block_metadata = 3;
}