hbase-protocol-shaded/src/main/protobuf/RPC.proto

   1 /**
   2  * Licensed to the Apache Software Foundation (ASF) under one
   3  * or more contributor license agreements.  See the NOTICE file
   4  * distributed with this work for additional information
   5  * regarding copyright ownership.  The ASF licenses this file
   6  * to you under the Apache License, Version 2.0 (the
   7  * "License"); you may not use this file except in compliance
   8  * with the License.  You may obtain a copy of the License at
   9  *
  10  *     http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  */
  18 syntax = "proto2";
  19 package hbase.pb;
  20
  21 import "Tracing.proto";
  22 import "HBase.proto";
  23
  24 option java_package = "org.apache.hadoop.hbase.shaded.protobuf.generated";
  25 option java_outer_classname = "RPCProtos";
  26 option java_generate_equals_and_hash = true;
  27 option optimize_for = SPEED;
  28
  29 // See https://issues.apache.org/jira/browse/HBASE-7898 for high-level
  30 // description of RPC specification.
  31 //
  32 // On connection setup, the client sends six bytes of preamble -- a four
  33 // byte magic, a byte of version, and a byte of authentication type.
  34 //
  35 // We then send a "ConnectionHeader" protobuf of user information and the
  36 // 'protocol' or 'service' that is to be run over this connection as well as
  37 // info such as codecs and compression to use when we send cell blocks(see below).
  38 // This connection header protobuf is prefaced by an int that holds the length
  39 // of this connection header (this is NOT a varint).  The pb connection header
  40 // is sent with Message#writeTo.  The server throws an exception if it doesn't
  41 // like what it was sent noting what it is objecting too.  Otherwise, the server
  42 // says nothing and is open for business.
  43 //
  44 // Hereafter the client makes requests and the server returns responses.
  45 //
  46 // Requests look like this:
  47 //
  48 // <An int with the total length of the request>
  49 // <RequestHeader Message written out using Message#writeDelimitedTo>
  50 // <Optionally a Request Parameter Message written out using Message#writeDelimitedTo>
  51 // <Optionally a Cell block>
  52 //
  53 // ...where the Request Parameter Message is whatever the method name stipulated
  54 // in the RequestHeader expects; e.g. if the method is a scan, then the pb
  55 // Request Message is a GetRequest, or a ScanRequest.  A block of Cells
  56 // optionally follows.  The presence of a Request param Message and/or a
  57 // block of Cells will be noted in the RequestHeader.
  58 //
  59 // Response is the mirror of the request:
  60 //
  61 // <An int with the total length of the response>
  62 // <ResponseHeader Message written out using Message#writeDelimitedTo>
  63 // <Optionally a Response Result Message written out using Message#writeDelimitedTo>
  64 // <Optionally a Cell block>
  65 //
  66 // ...where the Response Message is the response type that goes with the
  67 // method specified when making the request and the follow on Cell blocks may
  68 // or may not be there -- read the response header to find out if one following.
  69 // If an exception, it will be included inside the Response Header.
  70 //
  71 // Any time we write a pb, we do it with Message#writeDelimitedTo EXCEPT when
  72 // the connection header is sent; this is prefaced by an int with its length
  73 // and the pb connection header is then written with Message#writeTo.
  74 //
  75
  76 // User Information proto.  Included in ConnectionHeader on connection setup
  77 message UserInformation {
  78   required string effective_user = 1;
  79   optional string real_user = 2;
  80 }
  81
  82 // This is sent on connection setup after the connection preamble is sent.
  83 message ConnectionHeader {
  84   optional UserInformation user_info = 1;
  85   optional string service_name = 2;
  86   // Cell block codec we will use sending over optional cell blocks.  Server throws exception
  87   // if cannot deal.  Null means no codec'ing going on so we are pb all the time (SLOW!!!)
  88   optional string cell_block_codec_class = 3;
  89   // Compressor we will use if cell block is compressed.  Server will throw exception if not supported.
  90   // Class must implement hadoop's CompressionCodec Interface.  Can't compress if no codec.
  91   optional string cell_block_compressor_class = 4;
  92   optional VersionInfo version_info = 5;
  93   // the transformation for rpc AES encryption with Apache Commons Crypto
  94   optional string rpc_crypto_cipher_transformation = 6;
  95 }
  96
  97 // This is sent by rpc server to negotiate the data if necessary
  98 message ConnectionHeaderResponse {
  99   // To use Apache Commons Crypto, negotiate the metadata
 100   optional CryptoCipherMeta crypto_cipher_meta = 1;
 101 }
 102
 103 // Optional Cell block Message.  Included in client RequestHeader
 104 message CellBlockMeta {
 105   // Length of the following cell block.  Could calculate it but convenient having it too hand.
 106   optional uint32 length = 1;
 107 }
 108
 109 // At the RPC layer, this message is used to carry
 110 // the server side exception to the RPC client.
 111 message ExceptionResponse {
 112   // Class name of the exception thrown from the server
 113   optional string exception_class_name = 1;
 114   // Exception stack trace from the server side
 115   optional string stack_trace = 2;
 116   // Optional hostname.  Filled in for some exceptions such as region moved
 117   // where exception gives clue on where the region may have moved.
 118   optional string hostname = 3;
 119   optional int32 port = 4;
 120   // Set if we are NOT to retry on receipt of this exception
 121   optional bool do_not_retry = 5;
 122 }
 123
 124 /**
 125  * Cipher meta for Crypto
 126  */
 127 message CryptoCipherMeta {
 128   required string transformation = 1;
 129   optional bytes inKey = 2;
 130   optional bytes inIv = 3;
 131   optional bytes outKey = 4;
 132   optional bytes outIv = 5;
 133 }
 134
 135 // Header sent making a request.
 136 message RequestHeader {
 137   // Monotonically increasing call_id to keep track of RPC requests and their response
 138   optional uint32 call_id = 1;
 139   optional RPCTInfo trace_info = 2;
 140   optional string method_name = 3;
 141   // If true, then a pb Message param follows.
 142   optional bool request_param = 4;
 143   // If present, then an encoded data block follows.
 144   optional CellBlockMeta cell_block_meta = 5;
 145   // 0 is NORMAL priority.  200 is HIGH.  If no priority, treat it as NORMAL.
 146   // See HConstants.
 147   optional uint32 priority = 6;
 148   optional uint32 timeout = 7;
 149 }
 150
 151 message ResponseHeader {
 152   optional uint32 call_id = 1;
 153   // If present, then request threw an exception and no response message (else we presume one)
 154   optional ExceptionResponse exception = 2;
 155   // If present, then an encoded data block follows.
 156   optional CellBlockMeta cell_block_meta = 3;
 157 }