/**
 * 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.
 */

/**
 * These .proto interfaces are private and stable.
 * Please see https://hadoop.apache.org/docs/current/hadoop-project-dist/hadoop-common/Compatibility.html
 * for what changes are allowed for a *stable* .proto interface.
 */

// This file contains protocol buffers that are used throughout HDFS -- i.e.
// by the client, server, and data transfer protocols.
syntax = "proto2";

option java_package = "org.apache.hadoop.hdfs.protocol.proto";
option java_outer_classname = "HdfsServerProtos";
option java_generate_equals_and_hash = true;
package hadoop.hdfs;

import "hdfs.proto";
import "HAServiceProtocol.proto";

/**
 * Block access token information
 */
message BlockKeyProto {
  required uint32 keyId = 1;      // Key identifier
  required uint64 expiryDate = 2; // Expiry time in milliseconds
  optional bytes keyBytes = 3;    // Key secret
}

/**
 * Current key and set of block keys at the namenode.
 */
message ExportedBlockKeysProto {
  required bool isBlockTokenEnabled = 1;
  required uint64 keyUpdateInterval = 2;
  required uint64 tokenLifeTime = 3;
  required BlockKeyProto currentKey = 4;
  repeated BlockKeyProto allKeys = 5;
}

/**
 * Block and datanodes where is it located
 */
message BlockWithLocationsProto {
  required BlockProto block = 1;   // Block
  repeated string datanodeUuids = 2; // Datanodes with replicas of the block
  repeated string storageUuids = 3;  // Storages with replicas of the block
  repeated StorageTypeProto storageTypes = 4;

  optional bytes indices = 5;
  optional uint32 dataBlockNum = 6;
  optional uint32 cellSize = 7;
}

/**
 * List of block with locations
 */
message BlocksWithLocationsProto {
  repeated BlockWithLocationsProto blocks = 1;
}

/**
 * Editlog information with available transactions
 */
message RemoteEditLogProto {
  required uint64 startTxId = 1;  // Starting available edit log transaction
  required uint64 endTxId = 2;    // Ending available edit log transaction
  optional bool isInProgress = 3 [default = false];
}

/**
 * Enumeration of editlogs available on a remote namenode
 */
message RemoteEditLogManifestProto {
  repeated RemoteEditLogProto logs = 1;
  optional uint64 committedTxnId = 2;
}

/**
 * Namespace information that describes namespace on a namenode
 */
message NamespaceInfoProto {
  required string buildVersion = 1;         // Software revision version (e.g. an svn or git revision)
  required uint32 unused = 2;               // Retained for backward compatibility
  required string blockPoolID = 3;          // block pool used by the namespace
  required StorageInfoProto storageInfo = 4;// Node information
  required string softwareVersion = 5;      // Software version number (e.g. 2.0.0)
  optional uint64 capabilities = 6 [default = 0]; // feature flags
  optional NNHAStatusHeartbeatProto.State state = 7;
}

/**
 * State of a block replica at a datanode
 */
enum ReplicaStateProto {
  FINALIZED = 0;  // State of a replica when it is not modified
  RBW = 1;        // State of replica that is being written to
  RWR = 2;        // State of replica that is waiting to be recovered
  RUR = 3;        // State of replica that is under recovery
  TEMPORARY = 4;  // State of replica that is created for replication
}

/**
 * Block that needs to be recovered with at a given location
 */
message RecoveringBlockProto {
  required uint64 newGenStamp = 1;        // New genstamp post recovery
  required LocatedBlockProto block = 2;   // Block to be recovered
  optional BlockProto truncateBlock = 3;  // New block for recovery (truncate)

  optional ErasureCodingPolicyProto ecPolicy = 4;
  // block indices of striped internal blocks for each storage in LocatedBlock
  optional bytes blockIndices = 5;
}

/**
 * Unique signature to identify checkpoint transactions.
 */
message CheckpointSignatureProto {
  required string blockPoolId = 1;
  required uint64 mostRecentCheckpointTxId = 2;
  required uint64 curSegmentTxId = 3;
  required StorageInfoProto storageInfo = 4;
}

/**
 * Command returned from primary to checkpointing namenode.
 * This command has checkpoint signature that identifies
 * checkpoint transaction and is needed for further
 * communication related to checkpointing.
 */
message CheckpointCommandProto {
  // Unique signature to identify checkpoint transation
  required CheckpointSignatureProto signature = 1;

  // If true, return transfer image to primary upon the completion of checkpoint
  required bool needToReturnImage = 2;
}

/**
 * Command sent from one namenode to another namenode.
 */
message NamenodeCommandProto {
  enum Type {
    NamenodeCommand = 0;      // Base command
    CheckPointCommand = 1;    // Check point command
  }
  required uint32 action = 1;
  required Type type = 2;
  optional CheckpointCommandProto checkpointCmd = 3;
}

/**
 * void request
 */
message VersionRequestProto {
}

/**
 * Version response from namenode.
 */
message VersionResponseProto {
  required NamespaceInfoProto info = 1;
}

/**
 * Common node information shared by all the nodes in the cluster
 */
message StorageInfoProto {
  required uint32 layoutVersion = 1; // Layout version of the file system
  required uint32 namespceID = 2;    // File system namespace ID
  required string clusterID = 3;     // ID of the cluster
  required uint64 cTime = 4;         // File system creation time
}

/**
 * Information sent by a namenode to identify itself to the primary namenode.
 */
message NamenodeRegistrationProto {
  required string rpcAddress = 1;    // host:port of the namenode RPC address
  required string httpAddress = 2;   // host:port of the namenode http server
  enum NamenodeRoleProto {
    NAMENODE = 1;
    BACKUP = 2;
    CHECKPOINT = 3;
  }
  required StorageInfoProto storageInfo = 3;  // Node information
  optional NamenodeRoleProto role = 4 [default = NAMENODE];        // Namenode role
}

/**
 * state - State the NN is in when returning response to the DN
 * txid - Highest transaction ID this NN has seen
 */
message NNHAStatusHeartbeatProto {
  enum State {
    ACTIVE = 0;
    STANDBY = 1;
    OBSERVER = 2;
  }
  required State state = 1;
  required uint64 txid = 2;
}