/**
 * 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 HRegionInterface). 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
 * RpcRequest. At the data level this looks like
 * <length-of-serialized-RpcRequest-obj><RpcRequest-object serialized>
 *
 * The server sends back a RpcResponse object as response.
 * At the data level this looks like
 * <protobuf-encoded-length-of-serialized-RpcResponse-obj><RpcResponse-object serialized>
 *
 * 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.
 */
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;
  required 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.ipc.HRegionInterface"];
}


/**
 * The complete RPC request message
 */
message RpcRequest {
  /** Monotonically increasing callId, mostly to keep track of RPCs */
  required int32 callId = 1;
  /** The request bytes */
  optional bytes request = 2;
}

/**
 * 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;
}

/**
 * The complete RPC response message
 */
message RpcResponse {
  /** Echo back the callId the client sent */
  required int32 callId = 1;
  /** Did the RPC execution encounter an error at the server */
  required bool error = 2;
  /** Optional response bytes */
  optional bytes response = 3;
  /** Optional exception when error is true*/
  optional RpcException exception = 4;
}