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

/**
 * Specification of (unsecure) HBase RPC:
 *
 * Client needs to set up a connection first to a server serving a certain
 * HBase protocol (like ClientProtocol). Once the connection is set up, the 
 * client and server communicates on that channel for RPC requests/responses.
 * The sections below describe the flow. 
 * 
 * As part of setting up a connection to a server, the client needs to send
 * the ConnectionHeader header. At the data level, this looks like
 * <"hrpc"-bytearray><'5'[byte]><length-of-serialized-ConnectionHeader-obj[int32]><ConnectionHeader-object serialized>
 *
 * For every RPC that the client makes it needs to send the following
 * RpcRequestHeader and the RpcRequestBody. At the data level this looks like:
 *  <length-of-serialized-RpcRequestHeader + length-of-varint32-of-serialized-RpcRequestHeader + 
 *   length-of-serialized-RpcRequestBody + length-of-varint32-of-serialized-RpcRequestBody>
 *  <RpcRequestHeader [serialized using Message.writeDelimitedTo]>
 *  <RpcRequestBody [serialized using Message.writeDelimitedTo]>
 *
 * On a success, the server's protobuf response looks like
 *  <RpcResponseHeader-object [serialized using Message.writeDelimitedTo]>
 *  <RpcResponseBody-object [serialized using Message.writeDelimitedTo]>
 * On a failure, the server's protobuf response looks like
 *  <RpcResponseHeader-object [serialized using Message.writeDelimitedTo]>
 *  <RpcException-object [serialized using Message.writeDelimitedTo]>
 *
 * There is one special message that's sent from client to server -
 * the Ping message. At the data level, this is just the bytes corresponding
 *   to integer -1.
 */

import "Tracing.proto"; 

option java_package = "org.apache.hadoop.hbase.protobuf.generated";
option java_outer_classname = "RPCProtos";
option java_generate_equals_and_hash = true;
option optimize_for = SPEED;

message UserInformation {
  required string effectiveUser = 1;
  optional string realUser = 2;
}

message ConnectionHeader {
  /** User Info beyond what is established at connection establishment
   *  (applies to secure HBase setup)
   */
  optional UserInformation userInfo = 1;
  /** Protocol name for next rpc layer
   * the client created a proxy with this protocol name
   */
  optional string protocol = 2 [default = "org.apache.hadoop.hbase.client.ClientProtocol"];
}


/**
 * The RPC request header
 */
message RpcRequestHeader {
  /** Monotonically increasing callId, mostly to keep track of RPCs */
  required uint32 callId = 1;
  optional RPCTInfo tinfo = 2;
}
/**
 * The RPC request body
 */
message RpcRequestBody {
  /** Name of the RPC method */
  required string methodName = 1;

  /** Bytes corresponding to the client protobuf request. This is the actual
   *  bytes corresponding to the RPC request argument.
   */
  optional bytes request = 2;

  /** Some metainfo about the request. Helps us to treat RPCs with
   *  different priorities. For now this is just the classname of the request
   *  proto object. 
   */
  optional string requestClassName = 4;
}

/**
 * The RPC response header
 */
message RpcResponseHeader {
  /** Echo back the callId the client sent */
  required uint32 callId = 1;
  /** Did the RPC execution encounter an error at the server */
  enum Status {
    SUCCESS = 0;
    ERROR = 1;
    FATAL = 2;
  }
  required Status status = 2;
}
/**
 * The RPC response body
 */
message RpcResponseBody {
   /** Optional response bytes. This is the actual bytes corresponding to the
    *  return value of the invoked RPC.
    */
  optional bytes response = 1;
}
/**
 * At the RPC layer, this message is used to indicate
 * the server side exception to the RPC client.
 *
 * HBase RPC client throws an exception indicated
 * by exceptionName with the stackTrace.
 */
message RpcException {
  /** Class name of the exception thrown from the server */
  required string exceptionName = 1;

  /** Exception stack trace from the server side */
  optional string stackTrace = 2;
}