// Licensed to the Apache Software Foundation (ASF) under one
// or more contributor license agreements.  See the NOTICE file
// distributed with this work for additional information
// regarding copyright ownership.  The ASF licenses this file
// to you under the Apache License, Version 2.0 (the
// "License"); you may not use this file except in compliance
// with the License.  You may obtain a copy of the License at
//
//   http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing,
// software distributed under the License is distributed on an
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.  See the License for the
// specific language governing permissions and limitations
// under the License.
syntax = "proto2";
package kudu.tserver;

option java_package = "org.apache.kudu.tserver";

import "kudu/common/wire_protocol.proto";
import "kudu/consensus/metadata.proto";
import "kudu/fs/fs.proto";
import "kudu/rpc/rpc_header.proto";
import "kudu/tablet/metadata.proto";
import "kudu/util/pb_util.proto";

// RaftConfig tablet copy RPC calls.
service TabletCopyService {
  option (kudu.rpc.default_authz_method) = "AuthorizeServiceUser";

  // Establish a tablet copy session.
  rpc BeginTabletCopySession(BeginTabletCopySessionRequestPB)
      returns (BeginTabletCopySessionResponsePB);

  // Check whether the specified session is active.
  rpc CheckSessionActive(CheckTabletCopySessionActiveRequestPB)
      returns (CheckTabletCopySessionActiveResponsePB);

  // Fetch data (blocks, logs) from the server.
  rpc FetchData(FetchDataRequestPB)
      returns (FetchDataResponsePB);

  // End a tablet copy session, allow server to release resources.
  rpc EndTabletCopySession(EndTabletCopySessionRequestPB)
      returns (EndTabletCopySessionResponsePB);
}

// Tablet Copy-specific errors use this protobuf.
message TabletCopyErrorPB {
  extend kudu.rpc.ErrorStatusPB {
    optional TabletCopyErrorPB tablet_copy_error_ext = 102;
  }

  enum Code {
    // An error which has no more specific error code.
    // The code and message in 'status' may reveal more details.
    //
    // RPCs should avoid returning this, since callers will not be
    // able to easily parse the error.
    UNKNOWN_ERROR = 1;

    // The specified tablet copy session either never existed or has expired.
    NO_SESSION = 2;

    // Unknown tablet.
    TABLET_NOT_FOUND = 3;

    // Unknown data block.
    BLOCK_NOT_FOUND = 4;

    // Unknown WAL segment.
    WAL_SEGMENT_NOT_FOUND = 5;

    // Invalid request. Possibly missing parameters.
    INVALID_TABLET_COPY_REQUEST = 6;

    // Error reading or transferring data.
    IO_ERROR = 7;
  }

  // The error code.
  required Code code = 1 [ default = UNKNOWN_ERROR ];

  // The Status object for the error. This will include a textual
  // message that may be more useful to present in log messages, etc,
  // though its error code is less specific.
  required AppStatusPB status = 2;
}

message BeginTabletCopySessionRequestPB {
  // permanent_uuid of the requesting peer.
  required bytes requestor_uuid = 1;

  // tablet_id of the tablet the requester desires to bootstrap from.
  required bytes tablet_id = 2;
}

message BeginTabletCopySessionResponsePB {
  // Opaque session id assigned by the server.
  // No guarantees are made as to the format of the session id.
  required bytes session_id = 1;

  // Maximum session idle timeout between requests.
  // Learners will have to start over again if they reach this timeout.
  // A value of 0 means there is no timeout.
  required uint64 session_idle_timeout_millis = 2;

  // Active superblock at the time of the request.
  required tablet.TabletSuperBlockPB superblock = 3;

  // Identifiers for the WAL segments available for download.
  // Each WAL segment is keyed by its sequence number.
  repeated uint64 wal_segment_seqnos = 4;

  // A snapshot of the consensus state at the time that the
  // tablet copy session was started.
  required consensus.ConsensusStatePB initial_cstate = 5;

  // permanent_uuid of the responding peer.
  optional bytes responder_uuid = 6;
}

message CheckTabletCopySessionActiveRequestPB {
  // Valid Session ID returned by a BeginTabletCopySession() RPC call.
  required bytes session_id = 1;

  // Set keepalive to true to reset the session timeout timer.
  optional bool keepalive = 2 [default = false];
}

message CheckTabletCopySessionActiveResponsePB {
  // Whether the given session id represents an active tablet copy session.
  required bool session_is_active = 1;
}

// A "union" type that allows the same RPC call to fetch different types of
// data (data blocks or log files).
message DataIdPB {
  enum IdType {
    UNKNOWN = 0;
    BLOCK = 1;
    LOG_SEGMENT = 2;
  }

  // Indicator whether it's a block or log segment id.
  required IdType type = 1;

  // Exactly one of these must be set.
  optional BlockIdPB block_id = 2;          // To fetch a block.
  optional uint64 wal_segment_seqno = 3;    // To fetch a log segment.
}

message FetchDataRequestPB {
  // Valid Session ID returned by a BeginTabletCopySession() RPC call.
  required bytes session_id = 1;

  // The server will use this ID to determine the key and type of data
  // that was requested.
  required DataIdPB data_id = 2;

  // Offset into data to start reading from.
  // If not specified, the server will send the data from offset 0.
  optional uint64 offset = 3 [default = 0];

  // Maximum length of the chunk of data to return.
  // If max_length is not specified, or if the server's max is less than the
  // requested max, the server will use its own max.
  optional int64 max_length = 4 [default = 0];
}

// A chunk of data (a slice of a block, file, etc).
message DataChunkPB {
  // Offset into the complete data block or file that 'data' starts at.
  required uint64 offset = 1;

  // Actual bytes of data from the data block, starting at 'offset'.
  required bytes data = 2 [(kudu.REDACT) = true];

  // CRC32C of the bytes contained in 'data'.
  required fixed32 crc32 = 3;

  // Full length, in bytes, of the complete data block or file on the server.
  // The number of bytes returned in 'data' can certainly be less than this.
  required int64 total_data_length = 4;
}

message FetchDataResponsePB {
  // The server will automatically release the resources (i.e. close file, free
  // read buffers) for a given data resource after the last byte is read.
  // So, per-resource, chunks are optimized to be fetched in-order.
  required DataChunkPB chunk = 1;
}

message EndTabletCopySessionRequestPB {
  required bytes session_id = 1;

  // Set to true if bootstrap is successful.
  required bool is_success = 2;

  // Client-provided error message. The server will log this error so that an
  // admin can identify when bad things are happening with tablet copy.
  optional AppStatusPB error = 3;
}

message EndTabletCopySessionResponsePB {
}